flowstate-api-clients Package Skill

Package: @epicdm/flowstate-api-clients Repository: flowstate-platform Path: packages/flowstate-api-clients Version: 0.1.0

Use this published Dojo skill as the package-level entrypoint. For detailed workflows, use the package-local skills listed below.

Primary Package Workflow

FlowState API Clients Workflow

Status: Active Purpose: Keep generated gateway calls type-safe and compatible with the shared BaseClient. Scope: packages/flowstate-api-clients Trigger: A FlowState API endpoint, response type, smoke test, or consuming package needs a typed client change. Input: Endpoint path, HTTP method, request/response shape, auth expectations, and target service client. Output: Updated client method, matching types, and focused tests.

Workflow

1. Read src/base-client.ts before changing any service client. Preserve bearer auth, JSON encoding, injected fetch, 204 handling, and qs() semantics.
2. Update the matching src/types/<service>.ts first when request or response data changes. Avoid any; model optional fields explicitly.
3. Add or update the grouped method in src/<service>-client.ts. Follow existing nested groups such as PaymentClient.billing, PaymentClient.admin, and PaymentClient.treasury.
4. Export new public types through src/types/index.ts if consumers need them, and confirm src/index.ts already exports the client or type surface.
5. Add a test in src/__tests__/<service>-client.test.ts that injects fetch and asserts URL, method, headers, JSON body, and parsed response. For default base URL behavior, use the pattern in src/__tests__/gateway-defaults.test.ts.
6. Check downstream callers with rg "@epicdm/flowstate-api-clients|new .*Client|PaymentClient" packages --glob '!**/node_modules/**'.

Example

const client = new PaymentClient({ token: 'test-token', fetch: mockFetch })
await client.billing.usage({ tenantId: 'tenant_123' })

The request should go to https://api.epicflowstate.ai/payments/billing/usage?tenantId=tenant_123 with Authorization: Bearer test-token.

Verification

• yarn workspace @epicdm/flowstate-api-clients test
• yarn workspace @epicdm/flowstate-api-clients typecheck
• yarn workspace @epicdm/flowstate-api-clients build

Composition

• Use gateway-specs-openapi-bundle-workflow when the method comes from an OpenAPI bundle change.
• Use gateway-routes-route-table-workflow when path prefixes or gateway auth behavior are changing.

Package Skill Inventory

Skill Inventory: @epicdm/flowstate-api-clients

Created Skills

Candidate Future Skills

Source Evidence

• src/base-client.ts owns request mechanics.
• src/index.ts owns exported public surface.
• src/payment-client.ts shows endpoint grouping conventions used by the broader client set.
• src/__tests__/gateway-defaults.test.ts and service tests prove default URL and request behavior.

Review Gate

Review: @epicdm/flowstate-api-clients Skills

Result: Pass for package-local source-backed skill coverage.

Checks

• The skill is task-triggered and teaches the client-extension workflow, not a method inventory.
• Source paths and package scripts are explicit.
• Composition notes point agents to gateway specs/routes and smoke tests.
• Dojo sync is deferred; generated .flowstate/dojo files were not modified.

Residual Risk

Only one focused skill was created for this shard. Split payment or marketplace client workflows later if agents repeatedly need endpoint-specific examples.

Start with this skill to understand the package purpose, then use the package-local focused skills for specific workflows. Keep this Dojo version aligned with packages/flowstate-api-clients/package.json. Do not treat generated feature lists as lessons; use workflow evidence from CODE-REVIEW.md, SKILL-INVENTORY.md, and REVIEW.md.