@ai-matrx/applets 0.2.7

package/dist/index.js

@@ -0,0 +1,43 @@
+// src/types.ts
+var PAGE_ACTION_STREAM = "actions";
+var NAV_STREAM = "nav";
+var rowsStream = (alias) => `rows:${alias}`;
+var runStream = (requestId) => `run:${requestId}`;
+var valueStream = (name) => `value:${name}`;
+function ok(data) {
+  return { ok: true, data };
+}
+function fail(code, message, retryable = false, diagnostic) {
+  const error = { code, message, retryable };
+  if (diagnostic !== void 0) error.diagnostic = diagnostic;
+  return { ok: false, error };
+}
+function fromRecordsError(error) {
+  const out = { code: error.code, message: error.message, retryable: error.code === "unreachable" || error.code === "timed_out" };
+  if (error.diagnostic !== void 0) out.diagnostic = error.diagnostic;
+  return out;
+}
+function toAppletError(err, code = "internal") {
+  if (err && typeof err === "object") {
+    const o = err;
+    if (typeof o.code === "string" && typeof o.message === "string") {
+      const out = { code: o.code, message: o.message, retryable: o.retryable === true };
+      if (typeof o.diagnostic === "string") out.diagnostic = o.diagnostic;
+      return out;
+    }
+    if (err instanceof Error) return { code, message: err.message, retryable: false };
+  }
+  return { code, message: String(err), retryable: false };
+}
+export {
+  NAV_STREAM,
+  PAGE_ACTION_STREAM,
+  fail,
+  fromRecordsError,
+  ok,
+  rowsStream,
+  runStream,
+  toAppletError,
+  valueStream
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["/**\n * The Applets contract types (CONTRACTS v2 §0, §1, §3, §4, §6, §8).\n *\n * One owner per type. Types another package owns are RE-EXPORTED from it,\n * never redefined; types whose owner has not exported them yet are written\n * here structurally, each naming its owner and contract section, and are\n * replaced by a re-export the release the owner ships them.\n *\n * Framework-free: no React, no runtime imports. Every import below is a type.\n */\nimport type { EntityRefWithWords, Uuid as RecordsUuid } from \"@ai-matrx/records\";\nimport type { IntelligencePort as AgentsIntelligencePort } from \"@ai-matrx/agents/intelligence\";\nimport type { ActionResult, SurfacePort as AlchemySurfacePort } from \"@ai-matrx/alchemy/actions\";\nimport type { ScopeSpec } from \"@ai-matrx/code-runtime\";\nimport type { DataPort, DataSource, WhereClause } from \"@ai-matrx/records/data\";\nimport type { RecordsError } from \"@ai-matrx/records\";\n\n// ─── §0 — owned elsewhere, re-exported ─────────────────────────────────────\n\n/** `@ai-matrx/records` — a UUID string. */\nexport type Uuid = RecordsUuid;\n\n/** `@ai-matrx/records` (AP-3) — every link everywhere reads as `EntityRef[]` (`EntityRefWithWords`). */\nexport type EntityRef = EntityRefWithWords;\n\n/** `@ai-matrx/agents/intelligence` (AP-1). */\nexport type {\n  RunRef,\n  ServedInput,\n  RunEvent,\n  KindEnvelope,\n  MandateDescription,\n  RunRequest,\n  RunResult,\n  RunListing,\n  SoftMandateSpec,\n} from \"@ai-matrx/agents/intelligence\";\n\n/** `@ai-matrx/alchemy/actions` (AP-2). */\nexport type {\n  ActionDeclaration,\n  ActionInfo,\n  ActionContext,\n  ActionCaller,\n  ActionPolicy,\n  ActionRuns,\n} from \"@ai-matrx/alchemy/actions\";\n\n/** `@ai-matrx/code-runtime` (AP-5). */\nexport type { ScopeSpec, CompileResult, Finding } from \"@ai-matrx/code-runtime\";\n\n/**\n * `@ai-matrx/content-ir` — a registered kind slug. content-ir types it as a\n * plain string and exports no named alias; this is that string.\n */\nexport type KindRef = string;\n\n// ─── §0 — owned here ───────────────────────────────────────────────────────\n\n/**\n * The system's own sentence. Superset of `RecordsError` in the sense of the\n * contract: `code` + the store's `message`, plus `retryable`.\n */\nexport interface AppletError {\n  code: string;\n  message: string;\n  retryable: boolean;\n  diagnostic?: string;\n}\n\n/** Never throws: every port call and every hook write answers one of these. */\nexport type Result<T> = { ok: true; data: T } | { ok: false; error: AppletError };\n\nexport type Status = \"idle\" | \"loading\" | \"ready\" | \"saving\" | \"error\";\n\n// ─── §0/§4 — owned by @ai-matrx/records (AP-3), re-exported ──────────────\n//\n// AP-3 owns Column, Row, Values, Filter, Query, Page and DataPort (CONTRACTS\n// §0 and §4); `@ai-matrx/records/data` exports them. The frame sees only the\n// port (`DataPort`, no `subscribe`); `HostDataPort` is the host's producer\n// (amendment 2.2) and never crosses the channel.\n\nexport type {\n  Column,\n  Row,\n  Values,\n  Query,\n  Page,\n  DataPort,\n  HostDataPort,\n  RowsEvent,\n  DataSource,\n  DataEvents,\n  WhereClause,\n  WhereOp,\n  Lane,\n} from \"@ai-matrx/records/data\";\n\n/** CONTRACTS §4 one `where` clause — records' `WhereClause`. */\nexport type Filter = WhereClause;\n\n/** One source an Applet declared (CONTRACTS §2 `useSources`, §4 `sources()`) — records' `DataSource`. */\nexport type SourceInfo = DataSource;\n\n/** A refusal in the store's words (`RecordsError`) — what a DataPort answers. */\nexport type { RecordsError, RecordsResult } from \"@ai-matrx/records\";\n\n// ─── §3 / §6 — the ports as the host exposes them ──────────────────────────\n\n/**\n * CONTRACTS §3 `IntelligencePort` (owner `@ai-matrx/agents`, AP-1) as a host\n * port: the agents package's port minus its in-process `events` listener —\n * across the doorway, run events arrive on the host's `run:<requestId>`\n * stream instead (no port takes a function).\n */\nexport type IntelligencePort = Omit<AgentsIntelligencePort, \"events\">;\n\n/** CONTRACTS §6 `SurfacePort` (owner `@ai-matrx/alchemy`, AP-2). Events: `value:<name>`. */\nexport type SurfacePort = AlchemySurfacePort;\n\n/**\n * The payload of the `actions` event stream: a `runs: \"page\"` Action routed to\n * the frame (CONTRACTS §6). The frame answers with `surface.completeAction`.\n * `by` is a superset field so the handler's `ActionContext` is truthful.\n */\nexport interface PageActionEvent {\n  action: string;\n  input: unknown;\n  runId: string;\n  by?: \"person\" | \"agent\" | \"applet\" | \"automation\";\n}\n\n/** The stream page-Action runs arrive on. */\nexport const PAGE_ACTION_STREAM = \"actions\";\n/** The stream a host announces route changes on (payload: `NavLocation`). */\nexport const NAV_STREAM = \"nav\";\n\nexport const rowsStream = (alias: string): string => `rows:${alias}`;\nexport const runStream = (requestId: string): string => `run:${requestId}`;\nexport const valueStream = (name: string): string => `value:${name}`;\n\n/** Re-exported so hosts can type completeAction answers without importing alchemy. */\nexport type ActionAnswer<T = unknown> = ActionResult<T>;\n\n// ─── §8 — the Applet record ────────────────────────────────────────────────\n\nexport interface AppletPage {\n  path: string;\n  title: string;\n  file: string;\n  parent?: string;\n}\n\nexport interface AppletMandate {\n  alias: string;\n  key: string;\n}\n\nexport type AppletSource =\n  | { alias: string; table_id: Uuid; organization_id: Uuid }\n  | { alias: string; entity: string };\n\n/** CONTRACTS §8 `AppletRecord` (owner `@ai-matrx/applets`, AP-0). */\nexport interface AppletRecord {\n  id: Uuid;\n  version: number;\n  organizationId: Uuid;\n  slug: string;\n  published: boolean;\n  files: Record<string, string>;\n  entry: string;\n  scope: ScopeSpec;\n  pages: AppletPage[];\n  mandates: AppletMandate[];\n  sources: AppletSource[];\n  parentId: Uuid | null;\n  /** `applets/<id>` */\n  surfaceName: string;\n}\n\n// ─── §1 — the doorway ──────────────────────────────────────────────────────\n\nexport interface Viewer {\n  userId: Uuid | null;\n  organizationIds: Uuid[];\n  activeOrganizationId: Uuid | null;\n  guest: boolean;\n}\n\nexport interface NavLocation {\n  path: string[];\n  params: Record<string, string>;\n}\n\nexport interface KindComponentSource {\n  files: Record<string, string>;\n  entry: string;\n}\n\n/**\n * CONTRACTS §1 `AppletHost`. Every call is an async request with JSON in and\n * JSON out (kind envelopes allowed), scoped to ONE mounted Applet.\n */\nexport interface AppletHost {\n  viewer(): Promise<Viewer>;\n  record(): Promise<AppletRecord>;\n  child(appletId: Uuid): Promise<{ hostId: string }>;\n  kinds: {\n    definition(slug: string): Promise<Result<unknown>>;\n    component(slug: string, platform: string): Promise<Result<KindComponentSource | null>>;\n  };\n  pages: { definition(pageId: Uuid): Promise<Result<unknown>> };\n  data: DataPort;\n  intelligence: IntelligencePort;\n  surface: SurfacePort;\n  nav: { go(to: string): Promise<void>; current(): Promise<NavLocation> };\n  events: {\n    on(stream: string, filter: unknown): Promise<{ subscriptionId: string }>;\n    off(subscriptionId: string): Promise<void>;\n  };\n  reportError(err: AppletError & { where: string }): Promise<void>;\n}\n\n/** What the frame receives for each event (CONTRACTS §1). */\nexport interface EventMessage {\n  subscriptionId: string;\n  payload: unknown;\n}\n\n/**\n * The frame's side of the doorway: the contract's `AppletHost` plus the two\n * things §1 says the CHANNEL supplies — receiving `{ subscriptionId, payload }`\n * messages, and addressing a child host by the `hostId` that `child()` answered.\n * An in-page host implements these in memory; a sandbox host maps them onto a\n * message channel. Neither is a port: nothing here crosses the doorway as data.\n */\nexport interface AppletChannel extends AppletHost {\n  readonly hostId: string;\n  /** Subscribe to every event message for this host. Returns an unsubscribe. */\n  receive(listener: (message: EventMessage) => void): () => void;\n  /** The scoped host for a `hostId` that `child()` answered. */\n  forHost(hostId: string): AppletChannel | null;\n}\n\n// ─── helpers every half uses ───────────────────────────────────────────────\n\nexport function ok<T>(data: T): Result<T> {\n  return { ok: true, data };\n}\n\nexport function fail<T = never>(code: string, message: string, retryable = false, diagnostic?: string): Result<T> {\n  const error: AppletError = { code, message, retryable };\n  if (diagnostic !== undefined) error.diagnostic = diagnostic;\n  return { ok: false, error };\n}\n\n/**\n * A DataPort refusal (`RecordsError`) as the §0 `AppletError`: the store's code\n * and sentence verbatim, `retryable` true only where a second try could change\n * the answer (the call never reached the store, or ran out of time).\n */\nexport function fromRecordsError(error: RecordsError): AppletError {\n  const out: AppletError = { code: error.code, message: error.message, retryable: error.code === \"unreachable\" || error.code === \"timed_out\" };\n  if (error.diagnostic !== undefined) out.diagnostic = error.diagnostic;\n  return out;\n}\n\n/** Any thrown value → an `AppletError`, keeping a system sentence when there is one. */\nexport function toAppletError(err: unknown, code = \"internal\"): AppletError {\n  if (err && typeof err === \"object\") {\n    const o = err as Record<string, unknown>;\n    if (typeof o.code === \"string\" && typeof o.message === \"string\") {\n      const out: AppletError = { code: o.code, message: o.message, retryable: o.retryable === true };\n      if (typeof o.diagnostic === \"string\") out.diagnostic = o.diagnostic;\n      return out;\n    }\n    if (err instanceof Error) return { code, message: err.message, retryable: false };\n  }\n  return { code, message: String(err), retryable: false };\n}\n"],"mappings":";AAqIO,IAAM,qBAAqB;AAE3B,IAAM,aAAa;AAEnB,IAAM,aAAa,CAAC,UAA0B,QAAQ,KAAK;AAC3D,IAAM,YAAY,CAAC,cAA8B,OAAO,SAAS;AACjE,IAAM,cAAc,CAAC,SAAyB,SAAS,IAAI;AA2G3D,SAAS,GAAM,MAAoB;AACxC,SAAO,EAAE,IAAI,MAAM,KAAK;AAC1B;AAEO,SAAS,KAAgB,MAAc,SAAiB,YAAY,OAAO,YAAgC;AAChH,QAAM,QAAqB,EAAE,MAAM,SAAS,UAAU;AACtD,MAAI,eAAe,OAAW,OAAM,aAAa;AACjD,SAAO,EAAE,IAAI,OAAO,MAAM;AAC5B;AAOO,SAAS,iBAAiB,OAAkC;AACjE,QAAM,MAAmB,EAAE,MAAM,MAAM,MAAM,SAAS,MAAM,SAAS,WAAW,MAAM,SAAS,iBAAiB,MAAM,SAAS,YAAY;AAC3I,MAAI,MAAM,eAAe,OAAW,KAAI,aAAa,MAAM;AAC3D,SAAO;AACT;AAGO,SAAS,cAAc,KAAc,OAAO,YAAyB;AAC1E,MAAI,OAAO,OAAO,QAAQ,UAAU;AAClC,UAAM,IAAI;AACV,QAAI,OAAO,EAAE,SAAS,YAAY,OAAO,EAAE,YAAY,UAAU;AAC/D,YAAM,MAAmB,EAAE,MAAM,EAAE,MAAM,SAAS,EAAE,SAAS,WAAW,EAAE,cAAc,KAAK;AAC7F,UAAI,OAAO,EAAE,eAAe,SAAU,KAAI,aAAa,EAAE;AACzD,aAAO;AAAA,IACT;AACA,QAAI,eAAe,MAAO,QAAO,EAAE,MAAM,SAAS,IAAI,SAAS,WAAW,MAAM;AAAA,EAClF;AACA,SAAO,EAAE,MAAM,SAAS,OAAO,GAAG,GAAG,WAAW,MAAM;AACxD;","names":[]}