@m8t-stack/api-contract 0.1.0

package/dist/esm/me.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Wire DTO for `GET /api/me` — echoes back the validated caller identity
+ * from the proxy-attached headers.
+ *
+ * `principalId` is the generic caller id (the token `oid`), present for BOTH
+ * interactive users and service principals. `upn` is an optional human label
+ * present only on the interactive user path. `principalType` distinguishes the
+ * two; `appId` (the token `appid`) is threaded for service callers only.
+ *
+ * Single-tenant (E1): these fields are exposed, never used to filter. No
+ * tenant/owner semantics live here — that is E2.
+ */
+export interface MeResponse {
+    /** Generic caller id — the token `oid`. Present for user and service callers. */
+    principalId: string;
+    /** "user" for an interactive bearer, "service" for an app-only token. */
+    principalType?: "user" | "service";
+    /** The token `appid` — service callers only. */
+    appId?: string;
+    /** Human-readable user principal name — interactive user path only. */
+    upn?: string;
+    oid?: string;
+    tenantId?: string;
+}
+//# sourceMappingURL=me.d.ts.map

package/dist/esm/me.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"me.d.ts","sourceRoot":"","sources":["../../src/me.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,UAAU;IACzB,iFAAiF;IACjF,WAAW,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/dist/esm/me.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=me.js.map

package/dist/esm/me.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"me.js","sourceRoot":"","sources":["../../src/me.ts"],"names":[],"mappings":""}

package/dist/esm/reasons.d.ts

@@ -0,0 +1,12 @@
+/**
+ * String-literal union types for the `details.reason` field carried in
+ * `ApiResponse.error.details`. Centralizing these prevents drift between
+ * the backend's throws and the CLI's hint-lookup table.
+ */
+export type BadRequestReason = "body_not_json" | "empty_body" | "empty_patch" | "empty_patch_would_orphan" | "missing_agent_name" | "invalid_agent_name" | "empty_agent_name" | "cross_agent_conversation" | "title_required" | "title_empty" | "title_too_long" | "missing_handle" | "invalid_handle" | "empty_handle" | "handle_too_long" | "missing_display_name" | "invalid_display_name" | "display_name_empty" | "display_name_too_long" | "missing_identities" | "no_identities_provided" | "invalid_identities" | "invalid_channel_id" | "channel_id_too_long" | "channel_id_empty" | "unknown_channel" | "invalid_add_identities" | "invalid_remove_identities" | "missing_channel" | "invalid_channel" | "missing_binding_id" | "invalid_binding_id" | "empty_binding_id" | "binding_id_too_long" | "missing_bot_token" | "bot_token_empty" | "bot_token_too_long" | "no_adapter_registered" | "invalid_status_filter" | "invalid_channel_filter" | "cleanup_active_binding" | "invalid_bot_username" | "bot_username_too_long" | "channel_mismatch" | "webhook_payload_invalid" | "webhook_registration_rejected";
+export type UnauthenticatedReason = "missing_bearer" | "token_decode_failed" | "token_missing_identity" | "header_missing" | "downstream_auth_pattern" | "webhook_signature_invalid";
+export type NotFoundReason = "team_member_not_found" | "agent_not_found" | "conversation_not_found" | "binding_not_found";
+export type ConflictReason = "handle_exists" | "identity_claimed" | "binding_exists";
+export type UpstreamReason = "downstream_auth_pattern" | "table_storage_partial_write" | "table_storage_unavailable" | "key_vault_unavailable" | "kv_secret_malformed" | "cascade_partial_failure" | "service_bus_unavailable" | "webhook_registration_failed";
+export type InternalReason = "config";
+//# sourceMappingURL=reasons.d.ts.map

package/dist/esm/reasons.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasons.d.ts","sourceRoot":"","sources":["../../src/reasons.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,gBAAgB,GACxB,eAAe,GACf,YAAY,GACZ,aAAa,GACb,0BAA0B,GAC1B,oBAAoB,GACpB,oBAAoB,GACpB,kBAAkB,GAClB,0BAA0B,GAC1B,gBAAgB,GAChB,aAAa,GACb,gBAAgB,GAChB,gBAAgB,GAChB,gBAAgB,GAChB,cAAc,GACd,iBAAiB,GACjB,sBAAsB,GACtB,sBAAsB,GACtB,oBAAoB,GACpB,uBAAuB,GACvB,oBAAoB,GACpB,wBAAwB,GACxB,oBAAoB,GACpB,oBAAoB,GACpB,qBAAqB,GACrB,kBAAkB,GAClB,iBAAiB,GACjB,wBAAwB,GACxB,2BAA2B,GAC3B,iBAAiB,GACjB,iBAAiB,GACjB,oBAAoB,GACpB,oBAAoB,GACpB,kBAAkB,GAClB,qBAAqB,GACrB,mBAAmB,GACnB,iBAAiB,GACjB,oBAAoB,GACpB,uBAAuB,GACvB,uBAAuB,GACvB,wBAAwB,GACxB,wBAAwB,GACxB,sBAAsB,GACtB,uBAAuB,GACvB,kBAAkB,GAClB,yBAAyB,GACzB,+BAA+B,CAAC;AAEpC,MAAM,MAAM,qBAAqB,GAC7B,gBAAgB,GAChB,qBAAqB,GACrB,wBAAwB,GACxB,gBAAgB,GAChB,yBAAyB,GACzB,2BAA2B,CAAC;AAEhC,MAAM,MAAM,cAAc,GACtB,uBAAuB,GACvB,iBAAiB,GACjB,wBAAwB,GACxB,mBAAmB,CAAC;AAExB,MAAM,MAAM,cAAc,GAAG,eAAe,GAAG,kBAAkB,GAAG,gBAAgB,CAAC;AAErF,MAAM,MAAM,cAAc,GACtB,yBAAyB,GACzB,6BAA6B,GAC7B,2BAA2B,GAC3B,uBAAuB,GACvB,qBAAqB,GACrB,yBAAyB,GACzB,yBAAyB,GACzB,6BAA6B,CAAC;AAElC,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC"}

package/dist/esm/reasons.js

@@ -0,0 +1,7 @@
+/**
+ * String-literal union types for the `details.reason` field carried in
+ * `ApiResponse.error.details`. Centralizing these prevents drift between
+ * the backend's throws and the CLI's hint-lookup table.
+ */
+export {};
+//# sourceMappingURL=reasons.js.map

package/dist/esm/reasons.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasons.js","sourceRoot":"","sources":["../../src/reasons.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/esm/response.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The standard wire envelope every m8t-stack backend route returns.
+ * Single source of truth shared between backend (apps/web) and CLI (apps/cli).
+ */
+export type ApiResponse<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+};
+/**
+ * Type-narrowing extract of the error variant. Useful when you have a known
+ * failure envelope and want to dig into the error fields without re-narrowing.
+ */
+export type ApiErrorEnvelope = Extract<ApiResponse<unknown>, {
+    ok: false;
+}>["error"];
+/**
+ * Type guard for callers that received a parsed JSON of unknown shape.
+ */
+export declare function isApiResponse<T = unknown>(value: unknown): value is ApiResponse<T>;
+//# sourceMappingURL=response.d.ts.map

package/dist/esm/response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/response.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IACrB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GACrB;IACE,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC;CACH,CAAC;AAEN;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC,OAAO,CAAC,CAAC;AAErF;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAAC,CAAC,CAAC,CASlF"}

package/dist/esm/response.js

@@ -0,0 +1,16 @@
+/**
+ * Type guard for callers that received a parsed JSON of unknown shape.
+ */
+export function isApiResponse(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    if (v.ok === true && "data" in v)
+        return true;
+    if (v.ok === false && typeof v.error === "object" && v.error !== null) {
+        const e = v.error;
+        return typeof e.code === "string" && typeof e.message === "string";
+    }
+    return false;
+}
+//# sourceMappingURL=response.js.map

package/dist/esm/response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.js","sourceRoot":"","sources":["../../src/response.ts"],"names":[],"mappings":"AAqBA;;GAEG;AACH,MAAM,UAAU,aAAa,CAAc,KAAc;IACvD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,IAAI,CAAC,CAAC,EAAE,KAAK,IAAI,IAAI,MAAM,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9C,IAAI,CAAC,CAAC,EAAE,KAAK,KAAK,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ,IAAI,CAAC,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;QACtE,MAAM,CAAC,GAAG,CAAC,CAAC,KAAgC,CAAC;QAC7C,OAAO,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,CAAC;IACrE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/esm/service-bus.d.ts

@@ -0,0 +1,15 @@
+import type { InboundEnvelope } from "./inbound-envelope.js";
+/**
+ * The body of a Service Bus message on the `inbound-messages` queue.
+ * Locked per EPIC §14.3. Worker dequeues, deserializes, processes.
+ */
+export type InboundServiceBusMessageBody = InboundEnvelope;
+/**
+ * applicationProperties on each Service Bus message — enables cheap
+ * filtering at receive time without parsing the body.
+ */
+export interface InboundServiceBusApplicationProperties {
+    channel: string;
+    bindingId: string;
+}
+//# sourceMappingURL=service-bus.d.ts.map

package/dist/esm/service-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-bus.d.ts","sourceRoot":"","sources":["../../src/service-bus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D;;;GAGG;AACH,MAAM,MAAM,4BAA4B,GAAG,eAAe,CAAC;AAE3D;;;GAGG;AACH,MAAM,WAAW,sCAAsC;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB"}

package/dist/esm/service-bus.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=service-bus.js.map

package/dist/esm/service-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-bus.js","sourceRoot":"","sources":["../../src/service-bus.ts"],"names":[],"mappings":""}

package/dist/esm/team.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Wire DTOs for the team-management API surface.
+ * `/api/team` GET/POST, `/api/team/[handle]` GET/PATCH/DELETE.
+ */
+export type Channel = "telegram" | "slack" | "teams";
+export declare const CHANNELS: readonly Channel[];
+export declare function isChannel(v: unknown): v is Channel;
+export interface TeamMemberIdentities {
+    telegram?: string;
+    slack?: string;
+    teams?: string;
+}
+export interface TeamMember {
+    handle: string;
+    displayName: string;
+    identities: TeamMemberIdentities;
+    /** ISO 8601. Earliest addedAt across rows for this handle. */
+    addedAt: string;
+    /** Admin UPN who wrote the first row for this handle. */
+    addedBy: string;
+}
+export interface ListTeamResponse {
+    members: TeamMember[];
+}
+export interface CreateTeamRequest {
+    handle: string;
+    displayName: string;
+    identities: TeamMemberIdentities;
+}
+export interface PatchTeamRequest {
+    displayName?: string;
+    addIdentities?: TeamMemberIdentities;
+    removeIdentities?: Channel[];
+}
+export interface DeleteTeamResponse {
+    deleted: {
+        handle: string;
+        rows: number;
+    };
+}
+/**
+ * Partial-write failure shape returned in `UpstreamError.details.partial`
+ * when a multi-identity POST fails after at least one row was already written.
+ *
+ * `created` is the subset of `TeamMemberIdentities` we successfully persisted.
+ * `failed` is the single channel we stopped on (we abort on first failure;
+ * see lib/team-members.ts).
+ */
+export interface PartialWriteDetails {
+    created: TeamMemberIdentities;
+    failed: {
+        channel: Channel;
+        channelUserId: string;
+        originalMessage: string;
+    };
+}
+//# sourceMappingURL=team.d.ts.map

package/dist/esm/team.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"team.d.ts","sourceRoot":"","sources":["../../src/team.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,OAAO,CAAC;AAErD,eAAO,MAAM,QAAQ,EAAE,SAAS,OAAO,EAA4C,CAAC;AAEpF,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,OAAO,CAElD;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,oBAAoB,CAAC;IACjC,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,oBAAoB,CAAC;CAClC;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,oBAAoB,CAAC;IACrC,gBAAgB,CAAC,EAAE,OAAO,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3C;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,oBAAoB,CAAC;IAC9B,MAAM,EAAE;QACN,OAAO,EAAE,OAAO,CAAC;QACjB,aAAa,EAAE,MAAM,CAAC;QACtB,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;CACH"}

package/dist/esm/team.js

@@ -0,0 +1,9 @@
+/**
+ * Wire DTOs for the team-management API surface.
+ * `/api/team` GET/POST, `/api/team/[handle]` GET/PATCH/DELETE.
+ */
+export const CHANNELS = ["telegram", "slack", "teams"];
+export function isChannel(v) {
+    return v === "telegram" || v === "slack" || v === "teams";
+}
+//# sourceMappingURL=team.js.map

package/dist/esm/team.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"team.js","sourceRoot":"","sources":["../../src/team.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,CAAC,MAAM,QAAQ,GAAuB,CAAC,UAAU,EAAE,OAAO,EAAE,OAAO,CAAU,CAAC;AAEpF,MAAM,UAAU,SAAS,CAAC,CAAU;IAClC,OAAO,CAAC,KAAK,UAAU,IAAI,CAAC,KAAK,OAAO,IAAI,CAAC,KAAK,OAAO,CAAC;AAC5D,CAAC"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@m8t-stack/api-contract",
+  "version": "0.1.0",
+  "description": "Shared gateway HTTP request/response types and error model for the m8t-stack platform.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/m8t-run/m8t.git",
+    "directory": "packages/api-contract"
+  },
+  "homepage": "https://github.com/m8t-run/m8t/tree/main/packages/api-contract#readme",
+  "bugs": {
+    "url": "https://github.com/m8t-run/m8t/issues"
+  },
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "default": "./dist/cjs/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "packageManager": "pnpm@10.33.0",
+  "scripts": {
+    "build": "tsc && tsc -p tsconfig.cjs.json && echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",
+    "prepare": "pnpm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.eslint.json",
+    "lint": "eslint ."
+  }
+}