kv-session Package Skill

Package: @epicdm/kv-session Repository: flowstate-platform Path: packages/shared/kv-session 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

KV Session Management

Status: Active Purpose: Help agents use @epicdm/kv-session without changing its storage or cookie contracts. Scope: packages/shared/kv-session Trigger: Session creation, lookup, logout, or route auth work that imports @epicdm/kv-session. Input: A KVNamespace, cookie name, request headers, and typed session payload. Output: Correct session writes, cookie headers, session reads, or tests.

Workflow

1. Import only the needed helpers from @epicdm/kv-session.
2. Create sessions with createSession(kv, data, options) after validating the caller's input.
3. Send the cookie value from buildSessionCookie(sessionId, cookieName, options).
4. Read route sessions with requireSession<T>(kv, cookieName, request.headers) when the cookie is available, or getSession<T>(kv, sessionId) when the ID is already known.
5. Destroy sessions with destroySession(kv, sessionId) and clear the browser cookie with buildSessionClearCookie(cookieName).

Contracts

Example

const sessionId = await createSession(env.SESSIONS, { userId, email }, { ttlSeconds: 3600 })
const cookie = buildSessionCookie(sessionId, '__dashboard', { ttlSeconds: 3600 })
return new Response(null, { status: 302, headers: { 'Set-Cookie': cookie } })

Verification

• Run yarn workspace @epicdm/kv-session test after behavior changes.
• Run yarn workspace @epicdm/kv-session typecheck after type or API changes.
• Add tests next to src/__tests__/kv-session.test.ts for TTL, cookie, or missing-session behavior.

Package Skill Inventory

Skill Inventory: @epicdm/kv-session

Package Role

@epicdm/kv-session is the shared Cloudflare KV session helper for web packages that need typed session data, Set-Cookie construction, and cookie-to-session lookup.

Skills

Composition Notes

• Compose with app auth-client skills when an OIDC callback creates session data.
• Compose with route or middleware skills in apps that call getSession or requireSession.
• Do not compose this as a persistence abstraction for non-session KV data; keys and TTLs are session-specific.

Review Gate

Review Gate: @epicdm/kv-session Skills

Result

Pass.

Checks

• Skills are source-backed by src/index.ts and src/__tests__/kv-session.test.ts.
• Content describes callable workflows and edge cases rather than generated feature lists.
• Verification commands are package-local and safe.
• No files outside packages/shared/kv-session/.flowstate/skills were changed for this package.

Residual Risk

The package does not validate session payload shape at runtime. Callers should validate user input before storing it.

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