flowstate-api-core Package Skill

Package: @epicdm/flowstate-api-core Repository: flowstate-platform Path: packages/flowstate-api-core 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 Core Worker Workflow

Status: Active Purpose: Keep worker APIs consistent with the shared Hono/OpenAPI foundation. Scope: packages/flowstate-api-core and worker packages importing it. Trigger: A worker API needs shared app setup, auth, schemas, response helpers, or middleware debugging. Input: Worker config, route modules, auth requirements, bindings, and response schema needs. Output: Worker API code that composes with createApiApp and passes package-local tests.

Workflow

1. Start from src/factory.ts. createApiApp already wires error handling, CORS, optional auth, usage metering, /health, /openapi.json, and /docs.
2. Use ApiEnv<B> and BaseBindings from src/types.ts for typed Hono contexts. Do not invent parallel env/context shapes unless a worker adds specific bindings.
3. For auth, configure createAuthMiddleware through createApiApp({ auth }) unless the worker has a proven route-local need. Preserve publicPaths for /health, /openapi.json, and /docs.
4. Return responses with ok, created, paginated, noContent, and err from src/helpers/responses.ts so status/body conventions stay stable.
5. Put common route validation in src/schemas/* only when multiple workers can reuse it. Keep worker-specific schemas in the worker package.
6. Before changing shared middleware, check downstream imports with rg "@epicdm/flowstate-api-core" packages/worker-* packages --glob '!**/node_modules/**'.

Example

const app = createApiApp({
  title: 'Marketplace API',
  version: '0.1.0',
  description: 'Marketplace worker',
  auth: { jwt: true, internal: true },
})

Register worker routes after the factory call and use shared helpers inside handlers.

Verification

• yarn workspace @epicdm/flowstate-api-core test
• yarn workspace @epicdm/flowstate-api-core typecheck
• yarn workspace @epicdm/flowstate-api-core lint

Composition

• Use package-local worker API skills for route-specific behavior.
• Use gateway-specs-openapi-bundle-workflow when shared schema changes affect OpenAPI generation.

Package Skill Inventory

Skill Inventory: @epicdm/flowstate-api-core

Created Skills

Candidate Future Skills

Source Evidence

• src/factory.ts defines the app assembly sequence.
• src/middleware/auth.ts defines auth methods and Hono context population.
• src/helpers/responses.ts defines response helper status/body contracts.
• src/__tests__/* covers the public contract.

Review Gate

Review: @epicdm/flowstate-api-core Skills

Result: Pass for source-backed package-local workflow guidance.

Checks

• The skill focuses on worker API construction and shared middleware contracts.
• It names exact source files, downstream package search patterns, and package-local verification commands.
• It avoids duplicating every schema field or route from worker packages.
• Generated .flowstate/dojo files and API package code were not touched.

Residual Risk

Auth middleware deserves a separate deeper skill if future work changes JWT verification or API-key semantics.

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-core/package.json. Do not treat generated feature lists as lessons; use workflow evidence from CODE-REVIEW.md, SKILL-INVENTORY.md, and REVIEW.md.