# Worked Examples — Layer 3 & Layer 4 Dynamic Use Cases Three providers spanning different categories. Each shows what Layer 3 and Layer 4 look like in practice. --- ## Example 1 — Gmail (category: `messaging`) ### Layer 3 (provider-refined messaging use cases) ```yaml - id: cse_client_side_encryption name: Client-Side Encryption (CSE) description: Gmail-specific enterprise encryption where keys never leave the client mapping_hints: action_pattern: cse|client_side_encryption path_pattern: settings/cse|cseIdentities|cseKeypairs method_pattern: ^(GET|POST|PUT|PATCH|DELETE)$ parent_use_case: organize_email rationale: Gmail uniquely exposes CSE setup APIs — most email providers don't. - id: smime_certificate_management name: S/MIME Certificate Management description: Manage S/MIME signing certificates per send-as address mapping_hints: action_pattern: smime path_pattern: smimeInfo method_pattern: ^(GET|POST|PUT|DELETE)$ parent_use_case: signature_and_send_as rationale: Standard signature management doesn't cover the S/MIME-specific certificate upload + default selection workflow Gmail exposes. ``` ### Layer 4 (Gmail-specific use cases derived from the API surface) ```yaml - id: mailbox_history_replay name: Mailbox History Replay description: Replay mailbox changes since a given history ID mapping_hints: action_pattern: ^list_history$ path_pattern: ^history$ method_pattern: ^GET$ api_signal: /users/{userId}/history endpoint family rationale: Distinct sub-feature for incremental sync; not covered by any static catalog. - id: delegated_mailbox_access name: Delegated Mailbox Access description: Grant other users read/write access to a mailbox mapping_hints: action_pattern: delegate path_pattern: settings/delegates method_pattern: ^(GET|POST|PUT|PATCH|DELETE)$ api_signal: /users/{userId}/settings/delegates endpoint family ``` --- ## Example 2 — Stripe (category: `payments`) ### Layer 3 (provider-refined payments use cases) ```yaml - id: payment_intent_lifecycle name: Payment Intent Lifecycle description: Stripe's multi-step PaymentIntent state machine (confirm, capture, cancel) mapping_hints: action_pattern: ^(create|confirm|capture|cancel|update)_payment_intent path_pattern: payment_intents method_pattern: ^POST$ parent_use_case: process_payment rationale: Stripe exposes a 5-state lifecycle for charges that maps to one generic "process_payment" use case but is finer-grained. - id: setup_intent_management name: Setup Intent / Save Payment Method description: Save payment methods for future off-session charges mapping_hints: action_pattern: setup_intent path_pattern: setup_intents method_pattern: ^(GET|POST)$ parent_use_case: payment_method_management rationale: Stripe-specific concept; not in the generic payment_method_management. ``` ### Layer 4 (Stripe sub-products surfaced as use cases) ```yaml - id: connect_account_management name: Stripe Connect — Platform Accounts description: Manage connected accounts for marketplace / platform use cases mapping_hints: action_pattern: ^(create|update|delete)_account$ path_pattern: ^accounts$ method_pattern: ^(GET|POST|DELETE)$ api_signal: /v1/accounts/* endpoint family + Stripe Connect product - id: tax_rates_management name: Tax Rate Configuration description: Define and apply tax rates to invoices / payments mapping_hints: action_pattern: tax_rate path_pattern: tax_rates method_pattern: ^(GET|POST|PUT)$ api_signal: /v1/tax_rates endpoints ``` --- ## Example 3 — HubSpot (category: `crm`) ### Layer 3 (provider-refined CRM use cases) ```yaml - id: deal_stage_workflows name: Deal Stage Workflow Automation description: HubSpot's pipeline-stage automation triggers mapping_hints: action_pattern: (pipeline_stage|stage_workflow) path_pattern: pipelines/stages method_pattern: ^(GET|POST|PUT|PATCH)$ parent_use_case: deal_pipeline rationale: HubSpot exposes stage-level automation hooks; generic CRM deal_pipeline doesn't cover workflow trigger configuration. - id: custom_object_schemas name: Custom Object Schema Definition description: Define entirely new object types in HubSpot's CRM mapping_hints: action_pattern: (schema|custom_object) path_pattern: schemas method_pattern: ^(GET|POST|PUT|PATCH|DELETE)$ parent_use_case: custom_objects rationale: HubSpot's schemas system goes well beyond generic custom_objects — supports relations, search indexes, and association definitions. ``` ### Layer 4 (HubSpot sub-products) ```yaml - id: marketing_email_integration name: Marketing Email Integration description: Read marketing email events into CRM as engagements mapping_hints: action_pattern: marketing_email|email_event path_pattern: marketing/v3/emails method_pattern: ^GET$ api_signal: /marketing/v3/emails endpoint family — straddles CRM + marketing categories - id: line_items_management name: Line Items on Deals description: Quote-style line items attached to deals mapping_hints: action_pattern: line_item path_pattern: line_items method_pattern: ^(GET|POST|PUT|PATCH|DELETE)$ api_signal: /crm/v3/objects/line_items endpoint family ``` --- ## Patterns to notice across examples 1. **Layer 3 entries have `parent_use_case`** pointing at the Layer 2 entry they refine. Reviewers can quickly see the relationship. 2. **Layer 4 entries have `api_signal`** documenting which endpoint family triggered the use case. Helps validate the use case is grounded in real API surface. 3. **No `example_apis` field** — dynamic files declare detection rules only. The use_case → action_id mapping is derived from `mapping_hints` and emitted to `metadata/use_cases.yaml` by Phase 5B. 4. **Mapping hints are tight**, not catch-all. Each pattern is specific enough that it wouldn't accidentally match unrelated APIs. 5. **Rationale field** is optional but useful for Layer 3 entries — explains why this refinement is provider-specific and not generic.