Core: Data Model, Types & Interfaces

[ggondim]

Summary

Define all core TypeScript types, the abstract storage interface, and the abstract channel adapter interface. These contracts are the foundation that every other package implements against.

Tasks

Data Model & Types

• Define core types:
  • Channel — id, platform, credentials reference, metadata
  • Recipient — id, webhookUrl, apiKey, metadata
  • Thread — threadId (ot_thr_*), channelId, nativeThreadId (nullable), targetId, createdAt
  • Turn — turnId (ot_turn_*), threadId, direction (inbound/outbound), message, timestamp
  • Route — id, criteria (channel, group, DM, thread, mention, sender, content pattern), recipientId, priority
  • Envelope — threadId, turnId, replyTo, source, message (single object or array)
• Define A2H intent types: INFORM, COLLECT, AUTHORIZE, ESCALATE, RESULT
• Define message union type with duck-typing discriminator: presence of intent = A2H, otherwise = Chat SDK
• ID generation utilities (ot_thr_*, ot_turn_*, ot_tk_*, ot_ch_sk_*)

Storage Interface

• Define abstract StorageAdapter interface:
  • channels: CRUD
  • recipients: CRUD
  • threads: create, getById, getByNativeId, listByChannel
  • turns: create, listByThread
  • routes: CRUD, match(criteria) → Route[]
  • tokens: create (ephemeral), validate, revoke
• Define StorageAdapterFactory pattern for pluggable instantiation

Channel Adapter Interface

• Define abstract ChannelAdapter interface:
  • register(config) — set up webhook/subscription listeners
  • sendMessage(target, message) — send rendered message to channel
  • renderChatSDK(message, capabilities) — adapt Chat SDK message to platform
  • renderA2HInline(intent, capabilities) — render buttons/selects for A2H
  • captureResponse(thread, turn) — listen for response in thread/reply/DM
  • capabilities() — returns platform capability flags
• Define ChannelCapabilities type: { threads, buttons, selectMenus, replyMessages, dms, fileUpload }
• Integrate Vercel Chat SDK as the base adapter layer

Acceptance Criteria

• All types exported from packages/core
• Storage interface is fully abstract (no implementation)
• Channel adapter interface is fully abstract (no implementation)
• ID generation produces correctly prefixed, unique IDs
• Duck-typing discriminator correctly classifies Chat SDK vs A2H messages
• Unit tests for ID generation and message classification

Dependencies

• Project Bootstrap — Monorepo, CI, Dev Environment #1 (Project Bootstrap)

References

• VISION.md — Data Model
• VISION.md — Envelope
• PLAN.md — Phase 1.1-1.3

[claude]

@claude Implement this issue.

• Base branch: meta/17
• Create your working branch as: claude/17-2-data-model-types-interfaces
• Target your PR to meta/17
• Include fixes #2 in the PR body

Enable auto-merge on the PR.

[claude]

Claude finished @claude[bot]'s task in 12m 21s —— View job • claude/issue-2-20260410-2134 • Create PR ➔

---

Implementation: Core Data Model, Types & Interfaces

All 19 files implemented, committed, and pushed to branch claude/issue-2-20260410-2134.

• Gather context (read VISION.md, explore project structure)
• Understand the request and plan implementation
• Create monorepo root config (package.json with Bun workspaces, tsconfig.json)
• Define core data model types: Channel, Recipient, Thread, Turn, Route, Envelope
• Define A2H intent types (INFORM, COLLECT, AUTHORIZE, ESCALATE, RESULT) and A2HMessage
• Define message union type with duck-typing discriminator (intent field → A2H, otherwise → Chat SDK)
• Implement ID generation utilities using crypto.getRandomValues (cryptographically random, 16-char alphanumeric suffix)
• Define abstract StorageAdapter interface (channels/recipients/threads/turns/routes CRUD + token lifecycle)
• Define StorageAdapterFactory<TConfig> for pluggable instantiation
• Define abstract ChannelAdapter interface: register, sendMessage, renderChatSDK, renderA2HInline, captureResponse, capabilities
• Define ChannelCapabilities type: { threads, buttons, selectMenus, replyMessages, dms, fileUpload }
• Export all types and utilities from packages/core/src/index.ts
• Unit tests for ID generation (prefix, uniqueness ×100, type guards, ID_PREFIXES constants)
• Unit tests for message classification (all 5 intents, mixed arrays, complement invariant, helpers)
• Commit and push (19 files, 1,185 insertions)

Files Created

package.json                              ← Bun workspaces root
tsconfig.json                             ← strict TS base (ES2022, bundler, exactOptionalPropertyTypes)
packages/core/
  package.json
  tsconfig.json
  src/
    index.ts                              ← all public exports
    types/
      a2h.ts          ← A2HIntent, A2HMessage, A2HContext
      channel.ts      ← Channel, Platform, CreateChannelInput
      envelope.ts     ← Envelope, EnvelopeSource, Token
      message.ts      ← ChatSDKMessage, Attachment, OpenThreadsMessage, EnvelopeMessage
      recipient.ts    ← Recipient, CreateRecipientInput
      route.ts        ← Route, RouteCriteria, CreateRouteInput
      thread.ts       ← Thread, CreateThreadInput
      turn.ts         ← Turn, TurnDirection, CreateTurnInput
    interfaces/
      storage-adapter.ts   ← StorageAdapter, StorageAdapterFactory, CrudOperations, ...
      channel-adapter.ts   ← ChannelAdapter, ChannelCapabilities, ChannelConfig
    utils/
      id-generator.ts      ← generateThreadId/TurnId/TokenId/ChannelSecretKey + type guards
      message-classifier.ts ← isA2HMessage, isChatSDKMessage, classifyMessages, etc.
  tests/
    id-generator.test.ts
    message-classifier.test.ts

Note: gh pr create requires additional tool permissions that weren't available. Please create the PR using the link below.

| Branch