@peers-app/peers-sdk 0.26.5 → 0.27.0

package/dist/contracts/contract-definition-schema.d.ts

@@ -0,0 +1,251 @@
+import { z } from "zod";
+import { FieldType } from "../types/field-type";
+/**
+ * Checks a contract definition's structure: id, version, name, and its tables, tools,
+ * observables, and events with their fields. A `devTag` isn't part of it.
+ */
+export declare const contractDefinitionSchema: z.ZodObject<{
+    contractId: z.ZodString;
+    version: z.ZodNumber;
+    name: z.ZodString;
+    description: z.ZodString;
+    tables: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        primaryKeyName: z.ZodString;
+        fields: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            type: z.ZodNativeEnum<typeof FieldType>;
+            defaultValue: z.ZodOptional<z.ZodAny>;
+            optional: z.ZodOptional<z.ZodBoolean>;
+            isArray: z.ZodOptional<z.ZodBoolean>;
+            subType: z.ZodOptional<z.ZodString>;
+            fields: z.ZodOptional<z.ZodLazy<z.ZodArray<z.ZodType<import("../types/field-type").IField>>>>;
+            enumValues: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        }, "strip", z.ZodTypeAny, import("../types/field-type").IField, import("../types/field-type").IField>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        description: string;
+        fields: import("../types/field-type").IField[];
+        primaryKeyName: string;
+    }, {
+        name: string;
+        description: string;
+        fields: import("../types/field-type").IField[];
+        primaryKeyName: string;
+    }>, "many">;
+    tools: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        usageDescription: z.ZodString;
+        inputFields: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            type: z.ZodNativeEnum<typeof FieldType>;
+            defaultValue: z.ZodOptional<z.ZodAny>;
+            optional: z.ZodOptional<z.ZodBoolean>;
+            isArray: z.ZodOptional<z.ZodBoolean>;
+            subType: z.ZodOptional<z.ZodString>;
+            fields: z.ZodOptional<z.ZodLazy<z.ZodArray<z.ZodType<import("../types/field-type").IField>>>>;
+            enumValues: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        }, "strip", z.ZodTypeAny, import("../types/field-type").IField, import("../types/field-type").IField>, "many">;
+        outputFields: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            type: z.ZodNativeEnum<typeof FieldType>;
+            defaultValue: z.ZodOptional<z.ZodAny>;
+            optional: z.ZodOptional<z.ZodBoolean>;
+            isArray: z.ZodOptional<z.ZodBoolean>;
+            subType: z.ZodOptional<z.ZodString>;
+            fields: z.ZodOptional<z.ZodLazy<z.ZodArray<z.ZodType<import("../types/field-type").IField>>>>;
+            enumValues: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        }, "strip", z.ZodTypeAny, import("../types/field-type").IField, import("../types/field-type").IField>, "many">;
+        remoteAccessLevel: z.ZodOptional<z.ZodNumber>;
+        requiresWorkflowRun: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        usageDescription: string;
+        inputFields: import("../types/field-type").IField[];
+        outputFields: import("../types/field-type").IField[];
+        remoteAccessLevel?: number | undefined;
+        requiresWorkflowRun?: boolean | undefined;
+    }, {
+        name: string;
+        usageDescription: string;
+        inputFields: import("../types/field-type").IField[];
+        outputFields: import("../types/field-type").IField[];
+        remoteAccessLevel?: number | undefined;
+        requiresWorkflowRun?: boolean | undefined;
+    }>, "many">;
+    observables: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        valueType: z.ZodNativeEnum<typeof FieldType>;
+        value: z.ZodOptional<z.ZodObject<Omit<{
+            name: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            type: z.ZodNativeEnum<typeof FieldType>;
+            defaultValue: z.ZodOptional<z.ZodAny>;
+            optional: z.ZodOptional<z.ZodBoolean>;
+            isArray: z.ZodOptional<z.ZodBoolean>;
+            subType: z.ZodOptional<z.ZodString>;
+            fields: z.ZodOptional<z.ZodLazy<z.ZodArray<z.ZodType<import("../types/field-type").IField>>>>;
+            enumValues: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        }, "name">, "strip", z.ZodTypeAny, {
+            type: FieldType;
+            optional?: boolean | undefined;
+            description?: string | undefined;
+            defaultValue?: any;
+            isArray?: boolean | undefined;
+            subType?: string | undefined;
+            fields?: import("../types/field-type").IField[] | undefined;
+            enumValues?: (string | number | boolean)[] | undefined;
+        }, {
+            type: FieldType;
+            optional?: boolean | undefined;
+            description?: string | undefined;
+            defaultValue?: any;
+            isArray?: boolean | undefined;
+            subType?: string | undefined;
+            fields?: import("../types/field-type").IField[] | undefined;
+            enumValues?: (string | number | boolean)[] | undefined;
+        }>>;
+        writable: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        description: string;
+        valueType: FieldType;
+        writable: boolean;
+        value?: {
+            type: FieldType;
+            optional?: boolean | undefined;
+            description?: string | undefined;
+            defaultValue?: any;
+            isArray?: boolean | undefined;
+            subType?: string | undefined;
+            fields?: import("../types/field-type").IField[] | undefined;
+            enumValues?: (string | number | boolean)[] | undefined;
+        } | undefined;
+    }, {
+        name: string;
+        description: string;
+        valueType: FieldType;
+        writable: boolean;
+        value?: {
+            type: FieldType;
+            optional?: boolean | undefined;
+            description?: string | undefined;
+            defaultValue?: any;
+            isArray?: boolean | undefined;
+            subType?: string | undefined;
+            fields?: import("../types/field-type").IField[] | undefined;
+            enumValues?: (string | number | boolean)[] | undefined;
+        } | undefined;
+    }>, "many">;
+    events: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        payloadFields: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            type: z.ZodNativeEnum<typeof FieldType>;
+            defaultValue: z.ZodOptional<z.ZodAny>;
+            optional: z.ZodOptional<z.ZodBoolean>;
+            isArray: z.ZodOptional<z.ZodBoolean>;
+            subType: z.ZodOptional<z.ZodString>;
+            fields: z.ZodOptional<z.ZodLazy<z.ZodArray<z.ZodType<import("../types/field-type").IField>>>>;
+            enumValues: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        }, "strip", z.ZodTypeAny, import("../types/field-type").IField, import("../types/field-type").IField>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        description: string;
+        payloadFields: import("../types/field-type").IField[];
+    }, {
+        name: string;
+        description: string;
+        payloadFields: import("../types/field-type").IField[];
+    }>, "many">>;
+    requiresUserContext: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    description: string;
+    version: number;
+    contractId: string;
+    tables: {
+        name: string;
+        description: string;
+        fields: import("../types/field-type").IField[];
+        primaryKeyName: string;
+    }[];
+    tools: {
+        name: string;
+        usageDescription: string;
+        inputFields: import("../types/field-type").IField[];
+        outputFields: import("../types/field-type").IField[];
+        remoteAccessLevel?: number | undefined;
+        requiresWorkflowRun?: boolean | undefined;
+    }[];
+    observables: {
+        name: string;
+        description: string;
+        valueType: FieldType;
+        writable: boolean;
+        value?: {
+            type: FieldType;
+            optional?: boolean | undefined;
+            description?: string | undefined;
+            defaultValue?: any;
+            isArray?: boolean | undefined;
+            subType?: string | undefined;
+            fields?: import("../types/field-type").IField[] | undefined;
+            enumValues?: (string | number | boolean)[] | undefined;
+        } | undefined;
+    }[];
+    events?: {
+        name: string;
+        description: string;
+        payloadFields: import("../types/field-type").IField[];
+    }[] | undefined;
+    requiresUserContext?: boolean | undefined;
+}, {
+    name: string;
+    description: string;
+    version: number;
+    contractId: string;
+    tables: {
+        name: string;
+        description: string;
+        fields: import("../types/field-type").IField[];
+        primaryKeyName: string;
+    }[];
+    tools: {
+        name: string;
+        usageDescription: string;
+        inputFields: import("../types/field-type").IField[];
+        outputFields: import("../types/field-type").IField[];
+        remoteAccessLevel?: number | undefined;
+        requiresWorkflowRun?: boolean | undefined;
+    }[];
+    observables: {
+        name: string;
+        description: string;
+        valueType: FieldType;
+        writable: boolean;
+        value?: {
+            type: FieldType;
+            optional?: boolean | undefined;
+            description?: string | undefined;
+            defaultValue?: any;
+            isArray?: boolean | undefined;
+            subType?: string | undefined;
+            fields?: import("../types/field-type").IField[] | undefined;
+            enumValues?: (string | number | boolean)[] | undefined;
+        } | undefined;
+    }[];
+    events?: {
+        name: string;
+        description: string;
+        payloadFields: import("../types/field-type").IField[];
+    }[] | undefined;
+    requiresUserContext?: boolean | undefined;
+}>;

package/dist/contracts/contract-definition-schema.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.contractDefinitionSchema = void 0;
+const zod_1 = require("zod");
+const field_type_1 = require("../types/field-type");
+// A contract definition in the registry's form (`IContractDefinition`), as data: what
+// `frozen-contracts.json` stores and what an `alsoImplements` entry carries. It checks the
+// structure without normalizing: callers keep the original object, so IR keys this SDK doesn't
+// know yet survive.
+/**
+ * Checks a contract definition's structure: id, version, name, and its tables, tools,
+ * observables, and events with their fields. A `devTag` isn't part of it.
+ */
+exports.contractDefinitionSchema = zod_1.z.object({
+    contractId: zod_1.z.string().regex(/^[a-z0-9]{25}$/i),
+    version: zod_1.z.number().int().positive().safe(),
+    name: zod_1.z.string().min(1),
+    description: zod_1.z.string(),
+    tables: zod_1.z.array(zod_1.z.object({
+        name: zod_1.z.string().min(1),
+        description: zod_1.z.string(),
+        primaryKeyName: zod_1.z.string().min(1),
+        fields: zod_1.z.array(field_type_1.fieldSchema),
+    })),
+    tools: zod_1.z.array(zod_1.z.object({
+        name: zod_1.z.string().min(1),
+        usageDescription: zod_1.z.string(),
+        inputFields: zod_1.z.array(field_type_1.fieldSchema),
+        outputFields: zod_1.z.array(field_type_1.fieldSchema),
+        remoteAccessLevel: zod_1.z.number().optional(),
+        requiresWorkflowRun: zod_1.z.boolean().optional(),
+    })),
+    observables: zod_1.z.array(zod_1.z.object({
+        name: zod_1.z.string().min(1),
+        description: zod_1.z.string(),
+        valueType: zod_1.z.nativeEnum(field_type_1.FieldType),
+        value: field_type_1.fieldSchema.omit({ name: true }).optional(),
+        writable: zod_1.z.boolean(),
+    })),
+    events: zod_1.z
+        .array(zod_1.z.object({
+        name: zod_1.z.string().min(1),
+        description: zod_1.z.string(),
+        payloadFields: zod_1.z.array(field_type_1.fieldSchema),
+    }))
+        .optional(),
+    requiresUserContext: zod_1.z.boolean().optional(),
+});

package/dist/contracts/contract-provider-router.d.ts

@@ -10,6 +10,8 @@ import { type IContractTransport } from "./contract-transport";
 export interface IAuthorizedContractRoute {
     /** Canonical data-context route selected by the trusted host. */
     dataContextId?: string;
+    /** Provider whose policy authorized this call; dispatch must keep this selection. */
+    providerPackageId?: string;
     /** Optional caller context to pass to the resolved endpoint. */
     context?: IContractCallContext;
 }

package/dist/contracts/contract-provider-router.js

@@ -158,8 +158,11 @@ function createContractProviderRouter(transport, opts) {
             };
             // Provider selection happens on the executing device, so a remote route is
             // cached by target device rather than by a locally selected provider package.
-            const providerPackageId = !targetDeviceId && opts.resolveProviderPackageId
-                ? await opts.resolveProviderPackageId(endpointRequest)
+            const providerPackageId = !targetDeviceId
+                ? (authorization.providerPackageId ??
+                    (opts.resolveProviderPackageId
+                        ? await opts.resolveProviderPackageId(endpointRequest)
+                        : undefined))
                 : undefined;
             endpointRequest.providerPackageId = providerPackageId;
             const endpointKey = routeKey(call.contractId, call.version, providerPackageId, authorization.dataContextId, targetDeviceId);

package/dist/contracts/contract-proxy.d.ts

@@ -103,6 +103,11 @@ export interface IContractNotification {
     /** Originating event name — informational, for debugging/logging only. */
     name?: string;
 }
+/** A remote subscription with a setup acknowledgement, also used by reconnecting UI clients. */
+export interface IContractSubscription extends ISubscriptionResult {
+    /** True after initial attachment, or false if setup fails or a UI wait ends before attachment. */
+    readonly ready: Promise<boolean>;
+}
 /**
  * The consumer-side proxy for a single contract table. Any accessed name is forwarded
  * as a remote method call returning a promise, **except** `dataChanged`, which is a
@@ -120,7 +125,7 @@ export type IContractTableProxy = Record<string, (...args: any[]) => Promise<any
      * {@link ISubscriptionResult} whose `unsubscribe()` stops delivery.
      */
     dataChanged: {
-        subscribe(handler: (event: any) => void): ISubscriptionResult;
+        subscribe(handler: (event: any) => void): IContractSubscription;
     };
 };
 /** Standard {@link Table} methods the contract provider allows over the wire. */
@@ -237,12 +242,10 @@ export interface IContractToolContext {
      * Absent for trusted local callers (the signed-in UI session and the CLI).
      */
     callerPackageId?: string;
-    /** Trusted frame, retained across host-backed action dispatch; never from arguments. */
+    /** Trusted frame, retained across host-backed tool dispatch; never from arguments. */
     authority?: IIsolatedCallPrincipal;
     /** Select a target under this tool’s trusted frame; authority never belongs in arguments. */
     dispatchTool?: (target: IContractToolTarget, args: unknown) => Promise<any>;
-    /** Checked alias dispatch supplied only by the host provider. */
-    dispatchAction?: (name: string, args: unknown) => Promise<any>;
     /** Signed actor selected by the host. */
     actorUserId?: string;
     /** Incoming host frame for read-only infrastructure projections; preserves the turn ceiling. */
@@ -250,6 +253,51 @@ export interface IContractToolContext {
     /** Original turn context for read-only catalog projection, before infrastructure admission. */
     incomingCallContext?: IContractCallContext;
 }
+/**
+ * Member builders over one transport and data context, shared by {@link createContractConsumer}
+ * (every member a definition lists, built up front) and `hostContract` (each member built on
+ * first use, so it needs no definition). {@link IContractConsumerMembers.dispose} ends every
+ * member's subscriptions and refuses new calls.
+ */
+export interface IContractConsumerMembers {
+    /** A table: accessed methods forward as remote calls; `dataChanged` subscribes. */
+    table(name: string): IContractTableProxy;
+    /** A tool: each call runs it on the provider. */
+    tool(name: string): (...args: unknown[]) => Promise<any>;
+    /** Write one observable value; the provider checks writability and the value. */
+    setObservable(name: string, value: unknown): Promise<unknown>;
+    /** An event's subscribe surface. */
+    event(name: string): {
+        subscribe: (handler: (value: any) => void) => IContractSubscription;
+    };
+    /**
+     * A live mirror of an observable, subscribed now. `loaded` settles after the initial read;
+     * `refresh` reads the provider's value again. A local write calls `chainWrite` with a `send`
+     * that rejects when the provider refuses it, so the caller orders writes and handles failures.
+     * A write to a mirror made with `writable: false` throws before changing it.
+     */
+    observable(name: string, writable: boolean, chainWrite: (send: () => Promise<void>) => void): {
+        observable: Observable<any>;
+        loaded: Promise<void>;
+        refresh(): Promise<void>;
+    };
+    /** Detach every subscription and refuse new calls. Idempotent. */
+    dispose(): void;
+}
+/**
+ * Build the member builders for one contract over `transport`. See
+ * {@link IContractConsumerMembers}.
+ *
+ * @param contractId The contract's id.
+ * @param version The contract's version.
+ * @param transport Bidirectional channel to the provider.
+ * @param opts.dataContextId Optional data context to scope every call to.
+ * @param opts.providerPackageId Optional provider to address.
+ */
+export declare function createContractConsumerMembers(contractId: string, version: number, transport: IContractTransport, opts?: {
+    dataContextId?: string;
+    providerPackageId?: string;
+}): IContractConsumerMembers;
 /**
  * Build the **consumer** side of a contract proxy from a contract definition and a
  * transport. Member names come from the contract shape; table members are backed by a
@@ -327,12 +375,6 @@ export interface IContractResolution {
     version: number;
     tables?: Record<string, Table<any>>;
     tools?: Record<string, IContractToolImplementation>;
-    /** Tool used for alias catalog admission; defaults to a tool requesting preservation. */
-    actionDispatcher?: string;
-    /** Private canonical tools; selectors never carry their own numeric permissions. */
-    actionTools?: Record<string, IContractToolImplementation>;
-    /** Package-owned selector-to-tool mapping, validated by the host. */
-    actionAliases?: Record<string, string>;
     /**
      * Host-only capabilities appended as the final argument to provider tool functions.
      * Omit this for remote or otherwise untrusted provider routes.
@@ -413,14 +455,6 @@ export type ContractPermissionCheck = (call: IContractCall, context: IContractCa
  * for compatibility and isolated in-process providers that intentionally need the old gate.
  */
 export declare const sameUserContractPermissionCheck: ContractPermissionCheck;
-/** Validate private alias registrations before exposing any action wrapper. */
-export declare function validateContractActions(resolution: IContractResolution): void;
-/**
- * Project executable aliases using live tool metadata and trusted caller identity.
- *
- * Catalog filtering is advisory; execution rechecks every target.
- */
-export declare function authorizedContractActionNames(resolution: IContractResolution, context: IContractCallContext): Promise<string[]>;
 /** Dynamic local tool reference; provider pinning is required for package-owned actions. */
 export interface IContractToolTarget {
     contractId: string;