@oddington/sdk 0.1.21 → 0.1.23

package/dist/types/packages/sdk/src/public.d.ts

@@ -14,7 +14,9 @@ export type { RecordReadInput } from '../../../shared/record-capture.js';
 export type { RecordDeleteRequest, RecordUpdateRequest, RecordWriteRequest } from '../../../shared/record-write.js';
 export { RoutineRecordWriteError } from '../../../shared/record-write.js';
 export { AirtableOperationError } from '../../../shared/airtable-contract.js';
-export type { AirtableField, AirtableTable, AirtableRecord, AirtableListInput, AirtableGetInput, AirtableCreateInput, AirtableUpdateInput, AirtableDeleteInput, AirtableReceipt, AirtableWriteResult, AirtableClient, Connections } from '../../../shared/airtable-contract.js';
+export type { AirtableField, AirtableTable, AirtableRecord, AirtableListInput, AirtableGetInput, AirtableCreateInput, AirtableUpdateInput, AirtableDeleteInput, AirtableReceipt, AirtableWriteResult, AirtableClient } from '../../../shared/airtable-contract.js';
+export type { GmailRuntimeConnection, AirtableRuntimeConnection, RuntimeConnection } from '../../../shared/connection-runtime.js';
+export type { Connections } from '../../../shared/airtable-contract.js';
 export declare const connections: import('../../../shared/airtable-contract.js').Connections;
 export { DataOperationError } from '../../../shared/data-contract.js';
 export type { DataRepository, DataErrorCode, PublicValueDefinition, PublicField, CollectionSummary, CollectionSchema, QueryScalar, SelectionOptions, RecordSelection, RecordsQuery, DataValue, SelectedRecord, SelectionMetadata, RecordsResult, RecordsSearchOptions, RecordsSearchResult, HistoryListOptions, HistoryEntry, HistoryChangesOptions, HistoryChange, HistoryChangesResult, RecordIdentity, RecordCreation, RecordUpdateSet, DataPublication, DataChangeSet, DataEffect } from '../../../shared/data-contract.js';

package/dist/types/packages/sdk/src/routine-definition-types.d.ts

@@ -1,9 +1,12 @@
 import type { AppValueSchema } from '../../../shared/app-routine-contract.js';
 import type { File } from '../../../shared/files-contract.js';
 import type { Connections } from '../../../shared/airtable-contract.js';
+import type { RuntimeConnectionFor } from '../../../shared/connection-runtime.js';
 import type { DataRepository } from '../../../shared/data-contract.js';
 import type { Handler } from '../../../shared/inbox-contract.js';
 import type { files, RoutinePublicationClient } from './public.js';
+import type { RoutineAccess } from '../../../shared/routine-definition-contract.js';
+export type { RoutineAccess } from '../../../shared/routine-definition-contract.js';
 declare const valueType: unique symbol;
 /** Serializable declaration; the phantom type never carries authority. */
 export type RoutineSchema<Value, Defaulted extends boolean = boolean> = AppValueSchema & {
@@ -12,13 +15,6 @@ export type RoutineSchema<Value, Defaulted extends boolean = boolean> = AppValue
     readonly hasDefault?: Defaulted;
 };
 export type RoutineSchemaValue<Schema> = Schema extends RoutineSchema<infer Value> ? Value : undefined;
-export type RoutineAccess = {
-    readonly repositories?: Readonly<Record<string, 'read' | 'write'>>;
-    readonly connections?: readonly string[];
-    readonly models?: readonly string[];
-    readonly files?: 'read' | 'read-write';
-    readonly publish?: readonly ('asks' | 'digests')[];
-};
 export type RoutineStepOutput = {
     summary: unknown;
     data: unknown;
@@ -64,11 +60,18 @@ export type RoutineCapabilities<Access extends RoutineAccess> = {
     readonly files: Access['files'] extends 'read-write' ? typeof files : Access['files'] extends 'read' ? Pick<typeof files, 'get' | 'read'> : {};
     readonly connections: {
         airtable(name: ConnectionName<Access>): ReturnType<Connections['airtable']>;
+        get<Name extends Extract<NonNullable<Access['connections']>[number], string>>(name: Name): Promise<RuntimeConnectionFor<Name>>;
     };
     readonly inbox: Pick<RoutinePublicationClient, (Access['publish'] extends readonly string[] ? 'asks' extends Access['publish'][number] ? 'publishAsk' : never : never) | (Access['publish'] extends readonly string[] ? 'digests' extends Access['publish'][number] ? 'publishDigest' : never : never)>;
 };
+type RoutineStepCalls<Steps extends RoutineSteps> = {
+    [Key in keyof Steps]: {
+        input: Parameters<Steps[Key]['run']> extends [] ? [] : [input: RoutineInput<RoutineStepInput<Steps[Key]>>];
+        result: RoutineStepResult<Steps[Key]>;
+    };
+};
 export type RoutineRuntime<Steps extends RoutineSteps, Access extends RoutineAccess = RoutineAccess> = RoutineCapabilities<Access> & {
-    step<Key extends Extract<keyof Steps, string>>(id: Key, ...input: Parameters<Steps[Key]['run']> extends [] ? [] : [input: RoutineInput<RoutineStepInput<Steps[Key]>>]): Promise<RoutineStepResult<Steps[Key]>>;
+    step<Key extends Extract<keyof Steps, string>>(id: Key, ...input: RoutineStepCalls<Steps>[Key]['input']): Promise<RoutineStepCalls<Steps>[Key]['result']>;
 };
 export type RoutineDefinition<Input extends RoutineSchema<unknown> | undefined = RoutineSchema<unknown> | undefined, Steps extends RoutineSteps = RoutineSteps, Result extends RoutineSchema<unknown> | undefined = RoutineSchema<unknown> | undefined, Access extends RoutineAccess = RoutineAccess, Responses extends readonly Handler<any>[] = readonly Handler<any>[], Id extends string = string> = {
     readonly id: Id;
@@ -103,5 +106,6 @@ export type RoutineSchemaBuilders = {
     }): RoutineSchema<number, false>;
     boolean(): RoutineSchema<boolean, false>;
 };
-export type RoutineFileSchema = () => RoutineSchema<File, false>;
-export {};
+export type RoutineFileSchema = (options?: {
+    storage?: 'local' | 'remote';
+}) => RoutineSchema<File, false>;

package/dist/types/shared/airtable-contract.d.ts

@@ -73,6 +73,7 @@ export interface AirtableClient {
 }
 export interface Connections {
     airtable(name: string): AirtableClient;
+    get<Name extends string>(identity: Name): Promise<import('./connection-runtime.js').RuntimeConnectionFor<Name>>;
 }
 /** Safe provider failure. An uncertain or partial mutation must never be retried blindly. */
 export declare class AirtableOperationError extends Error {

package/dist/types/shared/app-descriptor.d.ts

@@ -1,4 +1,5 @@
 import type { AppValueSchema } from './app-routine-contract.js';
+import type { RoutineContract } from './routine-definition-contract.js';
 /** Build-time structure only. Runtime readiness and availability belong to hosts. */
 export type AppRoutineDescriptor = {
     id: string;
@@ -19,3 +20,5 @@ export type AppRoutineDescriptor = {
 export type AppDescriptor = {
     routines: AppRoutineDescriptor[];
 };
+/** The shared safe projection for generated apps and deployed preparation. */
+export declare function routineDefinitionDescriptor(contract: RoutineContract): AppRoutineDescriptor;

package/dist/types/shared/app-routine-contract.d.ts

@@ -29,6 +29,7 @@ export type AppValueSchema = {
     maximum?: number;
 } | {
     type: 'file';
+    storage?: 'local' | 'remote';
 };
 export type AppRoutineContract = {
     routine: string;

package/dist/types/shared/connection-runtime.d.ts

@@ -0,0 +1,20 @@
+/** Public values delivered only inside trusted routine or handler execution. */
+export type GmailRuntimeConnection = {
+    id: `gmail/${string}`;
+    provider: 'gmail';
+    name: string;
+    accountEmail: string;
+    scopes: string[];
+    accessToken: string;
+    expiresAt: string;
+};
+export type AirtableRuntimeConnection = {
+    id: `airtable/${string}`;
+    provider: 'airtable';
+    name: string;
+    baseId: string;
+    accessToken: string;
+    runExpiresAt: string;
+};
+export type RuntimeConnection = GmailRuntimeConnection | AirtableRuntimeConnection;
+export type RuntimeConnectionFor<Name extends string> = string extends Name ? RuntimeConnection : Name extends `gmail/${string}` ? GmailRuntimeConnection : Name extends `airtable/${string}` ? AirtableRuntimeConnection : never;

package/dist/types/shared/inbox-contract.d.ts

@@ -138,9 +138,15 @@ type Presentation = {
     body?: InboxBlock[];
     notifyImmediately?: boolean;
 };
+export type AskRecordRef = {
+    repository: string;
+    id: string;
+};
 export type AskInput = Presentation & {
     recipients?: string[];
     questions?: QuestionInput[];
+    tags?: string[];
+    recordRefs?: AskRecordRef[];
 };
 export type DigestInput = Presentation & {
     recipients: string[];
@@ -149,6 +155,8 @@ export type AskPublication = Presentation & {
     kind: 'ask';
     recipients: string[];
     questions: Question[];
+    tags: string[];
+    recordRefs: AskRecordRef[];
 };
 export type DigestPublication = DigestInput & {
     kind: 'digest';
@@ -333,7 +341,7 @@ export declare function validateHandlerTransition(value: unknown, state: {
 export declare function validateResolution(value: unknown): ResolutionInput;
 export type PublicationRequest = {
     requestKey: string;
-    item: Publication;
+    item: DigestPublication | (Omit<AskPublication, 'tags' | 'recordRefs'> & Pick<AskInput, 'tags' | 'recordRefs'>);
 };
 export type PublishedAsk = {
     id: string;

package/dist/types/shared/inbox-member-contract.d.ts

@@ -11,8 +11,8 @@ export declare const INBOX_LOCAL_INPUT_BYTES: number;
 export declare const INBOX_UUID: RegExp;
 export type InboxOperation = 'current' | 'items.list' | 'items.read' | 'items.see' | 'items.markDigestRead' | 'items.rename' | 'items.setLifecycle' | 'items.listRecipientCandidates' | 'items.addRecipient' | 'questions.list' | 'questions.answer' | 'questions.searchRecords' | 'files.read';
 export declare function isAppQuestionOperation(operation: InboxOperation): boolean;
-/** Closed wire vocabulary. Hosts select the listing mode; input cannot select it. */
-export declare function parseInboxRequest(value: unknown, questionListContext?: 'local' | 'hosted'): {
+/** Closed wire vocabulary; both placements require an explicit relevance filter. */
+export declare function parseInboxRequest(value: unknown): {
     operation: InboxOperation;
     input: Record<string, unknown>;
 };

package/dist/types/shared/inbox-member-types.d.ts

@@ -63,11 +63,11 @@ export type LinkedAskSnapshot = {
     state: 'unavailable';
     done: boolean;
 };
-export interface InboxItem {
+interface InboxItemSnapshot {
+    canonicalRoutineId?: string | null;
     id: string;
     workspaceId: string;
     number: number;
-    kind: 'ask' | 'digest';
     title: string;
     description: string;
     author: string;
@@ -104,6 +104,18 @@ export interface InboxItem {
         settledAt: string | null;
     }[];
 }
+export type InboxItem = InboxItemSnapshot & ({
+    kind: 'ask';
+    tags: string[];
+    recordRefs: Array<{
+        repository: string;
+        id: string;
+    }>;
+} | {
+    kind: 'digest';
+    tags?: never;
+    recordRefs?: never;
+});
 export interface DigestReadConfirmation {
     readAt: string;
     activityId: number;
@@ -116,23 +128,21 @@ export interface ResponseAcceptance {
     acceptanceOrder?: number;
 }
 export interface AnswerableQuestion {
-    item: {
-        id: string;
-        number: number;
-        revision: number;
-        title: string;
-        href: string;
-    };
-    origin: {
-        routine: string;
-    };
-    question: {
+    itemId: string;
+    revision: number;
+    title: string;
+    inboxUrl: string;
+    questionId: string;
+    routine: string;
+    prompt: string;
+    instructions?: string;
+    response: ResponseDefinition;
+    answerable: boolean;
+    tags: string[];
+    recordRefs: Array<{
+        repository: string;
         id: string;
-        prompt: string;
-        instructions: string | null;
-        response: ResponseDefinition;
-    };
-    recordRefs: string[];
+    }>;
 }
 export interface AskUpdate {
     item: InboxItem;
@@ -185,7 +195,7 @@ export interface InboxMember {
         }): Promise<RecipientAddition>;
     };
     questions: {
-        list(input?: InboxQuestionListInput): Promise<AnswerableQuestion[]>;
+        list(input: InboxQuestionListInput): Promise<AnswerableQuestion[]>;
         answer(input: InboxAnswerInput): Promise<ResponseAcceptance>;
         searchRecords(input: InboxSearchInput): Promise<RecordSelectionResult>;
     };
@@ -196,3 +206,4 @@ export interface InboxMember {
         }): Promise<Response>;
     };
 }
+export {};

package/dist/types/shared/routine-definition-contract.d.ts

@@ -0,0 +1,33 @@
+import { type AppValueSchema } from './app-routine-contract.js';
+export type RoutineAccess = {
+    readonly repositories?: Readonly<Record<string, 'read' | 'write'>>;
+    readonly connections?: readonly string[];
+    readonly models?: readonly string[];
+    readonly files?: 'read' | 'read-write';
+    readonly publish?: readonly ('asks' | 'digests')[];
+};
+export type RoutineContract = {
+    id: string;
+    title?: string;
+    input: AppValueSchema;
+    inputDefault?: unknown;
+    access: RoutineAccess;
+    responses: {
+        id: string;
+    }[];
+    steps: {
+        id: string;
+        title: string;
+    }[];
+    result?: AppValueSchema;
+};
+export declare const routineTitle: (value: unknown) => value is string;
+export declare function freezeRoutineMetadata<Value>(value: Value): Value;
+/** Reject values JSON would drop, rewrite, or obtain by invoking authored code. */
+export declare function assertRoutineJson(value: unknown, ancestors?: Set<object>): void;
+/** Inspect property descriptors before reading authored metadata or functions. */
+export declare function assertRoutineFields(value: unknown, allowed?: string[]): asserts value is Record<string, any>;
+export declare function parseRoutineAccess(value: unknown): RoutineAccess;
+/** Inert report/admission grammar shared with authoring; imports no runtime or
+ * capability modules and never constructs executable customer functions. */
+export declare function parseRoutineDefinitionContract(value: unknown): RoutineContract;

package/dist/types/shared/routine-deployment-contract.d.ts

@@ -0,0 +1,47 @@
+import type { RoutineSourceProvenance } from './routine-source-provenance.js';
+import type { RoutineContract } from './routine-definition-contract.js';
+export declare const ROUTINE_DECLARATION_SCHEMA = "https://schemas.oddington.ai/routine/v1.json";
+export declare const ROUTINE_SOURCE_LIMITS: {
+    files: number;
+    bytes: number;
+    declarationBytes: number;
+};
+export type RoutineDeclaration = {
+    $schema: typeof ROUTINE_DECLARATION_SCHEMA;
+    access: {
+        repositories: Record<string, 'read' | 'write'>;
+        connections: string[];
+        models: string[];
+        files?: 'read' | 'read-write';
+        publish: Array<'asks' | 'digests'>;
+    };
+    runtime: {
+        features: Array<'python' | 'documents' | 'browser'>;
+        resources: 'standard' | 'large';
+        maxDuration: string;
+    };
+    retry: {
+        maxAttempts: number;
+    };
+    assets: string[];
+};
+export type RoutineDeploymentSource = {
+    digest: string;
+    declaration: RoutineDeclaration;
+    definition?: {
+        entry: string;
+        contract: RoutineContract;
+    };
+    files: Array<{
+        path: string;
+        sha256: string;
+        size: number;
+    }>;
+    provenance?: RoutineSourceProvenance;
+};
+/** An authored definition has one fixed, private execution profile. */
+export declare function routineDefinitionDeclaration(contract: RoutineContract): RoutineDeclaration;
+export declare function routineDefinitionDirectory(entry: string): string;
+export declare const routineAlias: (value: unknown) => value is string;
+export declare function routineAssetPattern(value: unknown): value is string;
+export declare function parseRoutineDeclaration(value: unknown): RoutineDeclaration;

package/dist/types/shared/routine-deployment-path.d.ts

@@ -0,0 +1,6 @@
+export declare const isRoutineSourceDirectory: (value: string) => boolean;
+/** Both the collector and untrusted upload/build admission use this boundary. */
+export declare function eligibleDeploymentPath(path: string): boolean;
+/** Package metadata is admitted only at the root and selected direct child.
+ * Inventory parsing has no selection yet; sealing supplies the exact name. */
+export declare function eligibleDeploymentInputPath(path: string, routine?: string): boolean;

package/dist/types/shared/routine-source-provenance.d.ts

@@ -0,0 +1,7 @@
+/** Checkout evidence is descriptive and never selects routine authority. */
+export type RoutineSourceProvenance = {
+    branch?: string;
+    commit?: string;
+    dirty: boolean;
+};
+export declare function parseRoutineSourceProvenance(value: unknown): RoutineSourceProvenance;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oddington/sdk",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "Oddington routine and response-handler SDK",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",