@ziggs-ai/contracts 0.2.0 → 0.6.0

package/README.md

@@ -16,7 +16,7 @@ import { SERVER_EVENTS, isApiErrorBody } from '@ziggs-ai/contracts';
 | Module | Carries |
 | --- | --- |
 | `chat` | `GET /chats`, `GET /chats/:chatId/messages`, the message write paths |
-| `inbox` | `GET /inbox/attention`, `POST /inbox/seen` |
+| `inbox` | Agent request triage, `GET /inbox/attention`, `POST /inbox/seen` |
 | `error` | the one error body every handler answers in |
 | `socket` | frame names and payloads, both directions |
 | `vocabulary` | the closed value lists the above are built from |
@@ -29,3 +29,14 @@ knows exactly which wire it is talking to.
 
 The socket is a receive-only accelerator: every frame has an HTTP read that is
 the source of truth. A client that misses a frame catches up on its next read.
+
+## Releasing
+
+Change contract sources and bump `package.json` in the same pull request. CI
+rejects source changes without a newer version. Merging a version bump to main
+publishes that commit automatically after regenerating and checking the wire
+types. A `contracts-v<version>` tag remains available for manual releases.
+
+Release contracts before merging client dependency upgrades. Clients can test
+an unreleased version with a local `npm pack` tarball; local validation is not
+a registry publication.

package/dist/generated/agents.d.ts

@@ -7,7 +7,10 @@ export type OwnedAgent = {
     name: string;
     isDelegate: boolean;
     connected: boolean;
+    engaged: boolean;
     lastSeenAt: string | null;
+    platform: string | null;
+    platformLabel: string | null;
 };
 export type OwnedAgentsResponse = {
     agents: Array<OwnedAgent>;

package/dist/generated/artifacts.d.ts

@@ -0,0 +1,50 @@
+/**
+ * GENERATED from the backend OpenAPI spec — do not edit.
+ * Family: artifacts. Regenerate: backend 'pnpm docs:generate' then this script.
+ */
+export type ArtifactSenderPersona = {
+    id: string;
+    name: string;
+    image: string | null;
+};
+export type ArtifactSenderPresentation = {
+    persona: ArtifactSenderPersona;
+    mode: "persona" | "chain";
+};
+export type ArtifactSender = {
+    id: string;
+    type: "user" | "agent" | "service" | "system";
+    presentation?: ArtifactSenderPresentation;
+};
+export type ArtifactLinks = {
+    chatIds: Array<string>;
+    agreementIds: Array<string>;
+    taskIds: Array<string>;
+};
+export type ReachableArtifactEntry = {
+    artifactId: string;
+    text: string;
+    sender: ArtifactSender;
+    contentType: string;
+    name?: string | null;
+    visibility: "chat" | "agent-private";
+    timestamp: string;
+    service?: unknown;
+    linkRole?: "input" | "output";
+    reach: Array<"authored" | "chat" | "agreement" | "task" | "grant">;
+    links: ArtifactLinks;
+    filename?: string | null;
+    mime?: string | null;
+    byteSize?: number | null;
+    checksum?: string | null;
+    format?: "pdf" | "docx" | "hwpx" | "md" | "txt" | "html" | null;
+    extractionStatus?: "none" | "pending" | "ok" | "failed" | null;
+    extractionError?: string | null;
+    truncated?: boolean | null;
+    extractedArtifactId?: string | null;
+};
+export type ListReachableArtifactsResult = {
+    artifacts: Array<ReachableArtifactEntry>;
+    latestSequence: string | null;
+    truncated: Array<string>;
+};

package/dist/generated/artifacts.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/generated/chat-send.d.ts

@@ -0,0 +1,15 @@
+/**
+ * GENERATED from the backend OpenAPI spec — do not edit.
+ * Family: chatSend. Regenerate: backend 'pnpm docs:generate' then this script.
+ */
+export type DailyUsageView = {
+    messagesToday: number;
+    dailyLimit: number;
+};
+export type SendChatMessageResult = {
+    success: boolean;
+    message: string;
+    messageId: string;
+    chatId: string;
+    usage?: DailyUsageView;
+};

package/dist/generated/chat-send.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/generated/connections.d.ts

@@ -0,0 +1,18 @@
+/**
+ * GENERATED from the backend OpenAPI spec — do not edit.
+ * Family: connections. Regenerate: backend 'pnpm docs:generate' then this script.
+ */
+export type ConnectionView = {
+    connectionId: string;
+    ownerId: string;
+    provider: string;
+    externalAccountLabel?: string | null;
+    externalAccountId?: string | null;
+    scopesGranted?: Array<string>;
+    mcpServerUrl?: string | null;
+    status: string;
+    createdAt?: string;
+};
+export type ConnectionsListResponse = {
+    connections: Array<ConnectionView>;
+};

package/dist/generated/connections.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/generated/grants.d.ts

@@ -0,0 +1,43 @@
+/**
+ * GENERATED from the backend OpenAPI spec — do not edit.
+ * Family: grants. Regenerate: backend 'pnpm docs:generate' then this script.
+ */
+export type GrantScopeView = {
+    kind: "chat" | "agreement" | "org" | "artifact" | "task" | "connection" | "wallet" | "consent" | "inbox";
+    id: string;
+    label?: string;
+};
+export type GrantCaveatView = {
+    type: string;
+    value: unknown;
+};
+export type GrantBasis = {
+    kind: "creation" | "publication" | "membership" | "acceptance" | "agreement";
+    id: string | null;
+};
+export type GrantView = {
+    grantId: string;
+    issuerId: string;
+    holderId: string;
+    parentGrantId: string | null;
+    agreementId: string | null;
+    scope: GrantScopeView;
+    caveats: Array<GrantCaveatView>;
+    revoked: boolean;
+    expiresAt: string | null;
+    createdAt: string;
+    health: "active" | "expired" | "revoked";
+    holderKind?: "user" | "org" | "agent";
+    access?: "read" | "write" | "admit";
+    basis?: GrantBasis;
+};
+export type UnreadableRail = {
+    rail: string;
+    requiredScope: string;
+};
+export type ListGrantsResult = {
+    items: Array<GrantView>;
+    nextCursor: string | null;
+    hasMore: boolean;
+    unreadableRails?: Array<UnreadableRail>;
+};

package/dist/generated/grants.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/generated/payments.d.ts

@@ -0,0 +1,21 @@
+/**
+ * GENERATED from the backend OpenAPI spec — do not edit.
+ * Family: payments. Regenerate: backend 'pnpm docs:generate' then this script.
+ */
+export type WalletRef = {
+    walletId: string;
+    ownerId: string;
+    orgId: string | null;
+    currency: string;
+    status: string;
+};
+export type WalletListEntry = {
+    wallet: WalletRef;
+    balance: number;
+    availableBalance: number;
+    orgId: string | null;
+    isPrimary: boolean;
+};
+export type WalletsMineResponse = {
+    wallets: Array<WalletListEntry>;
+};

package/dist/generated/payments.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/identifiers.d.ts

@@ -0,0 +1,11 @@
+/** Wire routing and presentation conventions. These do not confer authority. */
+export declare const AGREEMENT_LANE_PREFIX = "agrn-";
+export declare const PERSONA_FACE_REF_PREFIX = "psn_";
+export declare const ROOM_BINDING_REF_PREFIX = "rpb_";
+export declare function agreementLaneId(agreementId: string): string;
+export declare function agreementIdFromLane(value: unknown): string | undefined;
+export declare function isAgreementLaneId(value: unknown): boolean;
+export declare function isAgreementId(value: unknown): value is string;
+export declare function isPersonaFaceRef(value: unknown): boolean;
+export declare function isRoomBindingRef(value: unknown): boolean;
+export declare function isPresentationRef(value: unknown): boolean;

package/dist/identifiers.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROOM_BINDING_REF_PREFIX = exports.PERSONA_FACE_REF_PREFIX = exports.AGREEMENT_LANE_PREFIX = void 0;
+exports.agreementLaneId = agreementLaneId;
+exports.agreementIdFromLane = agreementIdFromLane;
+exports.isAgreementLaneId = isAgreementLaneId;
+exports.isAgreementId = isAgreementId;
+exports.isPersonaFaceRef = isPersonaFaceRef;
+exports.isRoomBindingRef = isRoomBindingRef;
+exports.isPresentationRef = isPresentationRef;
+/** Wire routing and presentation conventions. These do not confer authority. */
+exports.AGREEMENT_LANE_PREFIX = 'agrn-';
+exports.PERSONA_FACE_REF_PREFIX = 'psn_';
+exports.ROOM_BINDING_REF_PREFIX = 'rpb_';
+function agreementLaneId(agreementId) {
+    return `${exports.AGREEMENT_LANE_PREFIX}${agreementId}`;
+}
+function agreementIdFromLane(value) {
+    if (typeof value !== 'string' || !value.startsWith(exports.AGREEMENT_LANE_PREFIX))
+        return undefined;
+    return value.slice(exports.AGREEMENT_LANE_PREFIX.length) || undefined;
+}
+function isAgreementLaneId(value) {
+    return agreementIdFromLane(value) !== undefined;
+}
+function isAgreementId(value) {
+    return typeof value === 'string' && value.startsWith('agr_');
+}
+function isPersonaFaceRef(value) {
+    return hasPrefix(value, exports.PERSONA_FACE_REF_PREFIX);
+}
+function isRoomBindingRef(value) {
+    return hasPrefix(value, exports.ROOM_BINDING_REF_PREFIX);
+}
+function isPresentationRef(value) {
+    return isPersonaFaceRef(value) || isRoomBindingRef(value);
+}
+function hasPrefix(value, prefix) {
+    return (typeof value === 'string' &&
+        value.length > prefix.length &&
+        value.startsWith(prefix));
+}

package/dist/inbox.d.ts

@@ -154,3 +154,16 @@ export interface AttentionFeed {
 export interface MarkInboxSeenBody {
     upTo: string;
 }
+/** Marketplace request triage channel shared by the server and hosted clients. */
+export interface InboxOpenRequestRef {
+    agreementId: string;
+    /** Exact-match triage string from the publisher (`metadata.match`). */
+    match: string;
+    title: string;
+    ts: string;
+}
+export interface InboxRequestChannel {
+    /** Unacked requests, separated from generic deliveries for exact-match triage. */
+    openRequestsAwaitingMe: InboxOpenRequestRef[];
+    truncatedRequests: number;
+}

package/dist/index.d.ts

@@ -12,3 +12,9 @@ export * from './inbox';
 export * from './error';
 export * from './socket';
 export * from './generated/agents';
+export * from './generated/grants';
+export * from './generated/payments';
+export * from './generated/connections';
+export * from './generated/artifacts';
+export * from './identifiers';
+export * from './generated/chat-send';

package/dist/index.js

@@ -29,3 +29,9 @@ __exportStar(require("./error"), exports);
 __exportStar(require("./socket"), exports);
 // Generated from the backend OpenAPI spec (ZIG-1668). See scripts/generate-wire.mjs.
 __exportStar(require("./generated/agents"), exports);
+__exportStar(require("./generated/grants"), exports);
+__exportStar(require("./generated/payments"), exports);
+__exportStar(require("./generated/connections"), exports);
+__exportStar(require("./generated/artifacts"), exports);
+__exportStar(require("./identifiers"), exports);
+__exportStar(require("./generated/chat-send"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/contracts",
-  "version": "0.2.0",
+  "version": "0.6.0",
   "description": "Wire contracts for the Ziggs API — response shapes, error body, and socket events, shared by every client.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,7 +9,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "node scripts/generate-wire.mjs && tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "prepack": "rm -rf dist && npm run build",
     "generate": "node scripts/generate-wire.mjs",