@oddington/sdk 0.1.23 → 0.1.25

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

@@ -2,7 +2,7 @@ import type { AskInput, CapturedRecords, DigestInput, InboxFile, PublicationRequ
 import type { FileAddOptions } from '../../../shared/inbox-files.js';
 import type { RecordReadInput } from '../../../shared/record-capture.js';
 import type { RecordDeleteRequest, RecordUpdateRequest, RecordWriteRequest } from '../../../shared/record-write.js';
-export type { RoutineSchema, RoutineSchemaValue, RoutineDefinition, RoutineInput, RoutineRuntime, RoutineAccess, RoutineCapabilities, RoutineStep, RoutineSteps, RoutineStepInput, RoutineStepResult, RoutineStepOutput, RoutineArtifactInput, RoutineArtifact } from './routine-definition-types.js';
+export type { RoutineSchema, RoutineSchemaValue, RoutineDefinition, RoutineInput, RoutineRuntime, RoutineAccess, RoutineCapabilities, RoutineStep, RoutineSteps, RoutineStepInput, RoutineStepResult, RoutineStepOutput, RoutineArtifactInput, RoutineArtifact, RoutineAI } from './routine-definition-types.js';
 export declare const defineRoutine: import('./routine-definition-types.js').DefineRoutine;
 export declare const schema: import('./routine-definition-types.js').RoutineSchemaBuilders;
 export declare const file: import('./routine-definition-types.js').RoutineFileSchema;
@@ -15,11 +15,11 @@ export type { RecordDeleteRequest, RecordUpdateRequest, RecordWriteRequest } fro
 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 } from '../../../shared/airtable-contract.js';
-export type { GmailRuntimeConnection, AirtableRuntimeConnection, RuntimeConnection } from '../../../shared/connection-runtime.js';
+export type { GmailRuntimeConnection, AirtableRuntimeConnection, DropboxRuntimeConnection, 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';
+export type { DataRepository, DataErrorCode, PublicValueDefinition, PublicField, CollectionSummary, CollectionSchema, QueryScalar, SelectionOptions, RecordSelection, RecordsQuery, DataValue, SelectedRecord, SelectionMetadata, RecordsResult, RecordsReadInput, RecordsReadResult, RecordsSearchOptions, RecordsSearchResult, HistoryListOptions, HistoryEntry, HistoryChangesOptions, HistoryChange, HistoryChangesResult, RecordIdentity, RecordCreation, RecordUpdateSet, DataPublication, DataChangeSet, DataEffect } from '../../../shared/data-contract.js';
 export declare const data: {
     repository(name: string): import('../../../shared/data-contract.js').DataRepository;
 };
@@ -185,6 +185,14 @@ export type AppRoutineBinding<Input, Result, Steps> = {
 };
 export declare const app: {
     listRoutines(): Promise<RoutineDescription[]>;
+    routine(id: string): {
+        describe(): Promise<RoutineDescription>;
+        run(input?: unknown): Promise<RunHandle>;
+        runs: {
+            list(): Promise<RunSummary[]>;
+            get(id: string): Promise<RunHandle>;
+        };
+    };
     routines: AppRoutineTypes;
 };
 /** A declared stage without a summary takes no second argument. */

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

@@ -6,6 +6,7 @@ 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';
+import type { RoutineAIInput } from '../../../shared/routine-ai-contract.js';
 export type { RoutineAccess } from '../../../shared/routine-definition-contract.js';
 declare const valueType: unique symbol;
 /** Serializable declaration; the phantom type never carries authority. */
@@ -15,6 +16,21 @@ 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 RoutineAI = {
+    generateText(input: {
+        instructions: string;
+        input: RoutineAIInput;
+    }): Promise<{
+        text: string;
+    }>;
+    generateObject<Schema extends RoutineSchema<unknown>>(input: {
+        instructions: string;
+        input: RoutineAIInput;
+        schema: Schema;
+    }): Promise<{
+        object: RoutineSchemaValue<Schema>;
+    }>;
+};
 export type RoutineStepOutput = {
     summary: unknown;
     data: unknown;
@@ -54,6 +70,7 @@ export type RoutineCapabilities<Access extends RoutineAccess> = {
     readonly run: {
         readonly id: string;
     };
+    readonly ai: Access['ai'] extends true ? RoutineAI : {};
     readonly data: {
         repository<Name extends Extract<keyof Access['repositories'], string>>(name: Name): RepositoryFor<NonNullable<Access['repositories']>[Name]>;
     };
@@ -66,7 +83,7 @@ export type RoutineCapabilities<Access extends RoutineAccess> = {
 };
 type RoutineStepCalls<Steps extends RoutineSteps> = {
     [Key in keyof Steps]: {
-        input: Parameters<Steps[Key]['run']> extends [] ? [] : [input: RoutineInput<RoutineStepInput<Steps[Key]>>];
+        input: Parameters<Steps[Key]['run']> extends [] ? [] : [input: RoutineStepInput<Steps[Key]> | RoutineInput<RoutineStepInput<Steps[Key]>>];
         result: RoutineStepResult<Steps[Key]>;
     };
 };

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

@@ -16,5 +16,16 @@ export type AirtableRuntimeConnection = {
     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;
+export type DropboxRuntimeConnection = {
+    id: `dropbox/${string}`;
+    provider: 'dropbox';
+    name: string;
+    accountId: string;
+    access: 'full_dropbox';
+    rootPath: string;
+    scopes: string[];
+    accessToken: string;
+    expiresAt: string;
+};
+export type RuntimeConnection = GmailRuntimeConnection | AirtableRuntimeConnection | DropboxRuntimeConnection;
+export type RuntimeConnectionFor<Name extends string> = string extends Name ? RuntimeConnection : Name extends `gmail/${string}` ? GmailRuntimeConnection : Name extends `airtable/${string}` ? AirtableRuntimeConnection : Name extends `dropbox/${string}` ? DropboxRuntimeConnection : never;

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

@@ -102,11 +102,26 @@ export type SelectionMetadata = {
         next?: string;
     }>;
 };
-export type RecordsResult = {
+type SelectedRecordFor<Selection extends RecordSelection> = string extends keyof Selection ? SelectedRecord : SelectedRecord & {
+    [Link in Exclude<keyof Selection, '$'>]?: SelectedLinkFor<Selection[Link]>;
+};
+type SelectedLinkFor<Selection> = Selection extends RecordSelection ? SelectedRecordFor<Selection> | SelectedRecordFor<Selection>[] | null : never;
+export type RecordsResult<Query extends RecordsQuery = RecordsQuery> = string extends keyof Query ? {
     $meta: SelectionMetadata;
     [collection: string]: SelectedRecord[] | SelectionMetadata;
+} : {
+    $meta: SelectionMetadata;
+} & {
+    [Collection in keyof Query]: SelectedRecordFor<Query[Collection]>[];
 };
 export type RecordIdentity = Pick<SelectedRecord, '$ref' | '$version'>;
+export type RecordsReadInput = string | readonly string[];
+export type RecordsReadResult = {
+    $meta: {
+        version: string;
+    };
+    records: Array<SelectedRecord | null>;
+};
 export type RecordsSearchOptions = {
     collections?: string[];
     limit?: number;
@@ -190,7 +205,14 @@ export interface DataRepository {
         schema(name: string): Promise<CollectionSchema>;
     };
     records: {
-        select(query: RecordsQuery): Promise<RecordsResult>;
+        select<Query extends RecordsQuery>(query: Query): Promise<RecordsResult<Query>>;
+        pages<Query extends RecordsQuery>(query: Query): AsyncIterable<RecordsResult<Query>>;
+        all<Query extends RecordsQuery>(query: Query, options: {
+            maxRecords: number;
+        }): Promise<RecordsResult<Query>>;
+        read(ref: string): Promise<SelectedRecord | null>;
+        read(refs: readonly string[]): Promise<RecordsReadResult>;
+        read(input: RecordsReadInput): Promise<SelectedRecord | null | RecordsReadResult>;
         search(query: string, options?: RecordsSearchOptions): Promise<RecordsSearchResult>;
     };
     history: {

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

@@ -77,20 +77,29 @@ export declare function parseFileEnrichMetadata(value: unknown, maxBytes: number
 export declare function safeFileName(value: unknown): value is string;
 export declare function safeFilePath(value: unknown): value is string;
 /** Private transport metadata: normalized material options exclude the request key and size declaration. */
+export declare const ORIGINAL_MEDIA_TYPES: readonly ['application/pdf', 'text/plain', 'text/markdown', 'application/json', 'image/png', 'image/jpeg'];
+export type OriginalMediaType = typeof ORIGINAL_MEDIA_TYPES[number];
+/** Normalize declarations only; no byte interpretation or filename inference. */
+export declare function declaredOriginalMediaType(value: string): OriginalMediaType | undefined;
 export type FileCreateMetadata = {
     name: string;
     path: string;
     storage?: FileStorage;
     csv?: Required<FileCsvHints>;
-    inputMediaType?: 'application/pdf';
+    inputMediaType?: OriginalMediaType;
     size: number;
     requestKey: string;
 };
-/** A declared PDF is descriptive metadata; this rule never reads original bytes. */
+/** Declared types are descriptive metadata; this rule never reads original bytes. */
 export declare function declaredOriginalFormat(input: Pick<FileCreateMetadata, 'name' | 'inputMediaType'>): {
     mediaType: 'application/pdf';
     details: {
         kind: 'pdf';
     };
+} | {
+    mediaType: "application/json" | "image/jpeg" | "image/png" | "text/markdown" | "text/plain";
+    details: {
+        kind: 'other';
+    };
 } | undefined;
 export declare function parseFileCreateMetadata(value: unknown, maxBytes: number): FileCreateMetadata;

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

@@ -129,6 +129,8 @@ export interface ResponseAcceptance {
 }
 export interface AnswerableQuestion {
     itemId: string;
+    /** Parent Ask's workspace-scoped Inbox number, stable across revisions. */
+    number: number;
     revision: number;
     title: string;
     inboxUrl: string;

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

@@ -0,0 +1,40 @@
+import { type AppValueSchema } from './app-routine-contract.js';
+import { type File } from './files-contract.js';
+/** Control values, explicit text and accepted output share the Run value bound.
+ * Raw Files have no universal AI byte cap: adapters must measure their final
+ * encoded request against their own transport limit before dispatch. */
+export declare const ROUTINE_AI_VALUE_BYTES: number;
+export declare const ROUTINE_AI_EVIDENCE_BYTES: number;
+export declare const ROUTINE_AI_OPERATION_MS = 120000;
+export declare const ROUTINE_AI_ERROR_CODES: readonly ['access_denied', 'capability_unavailable', 'invalid_input', 'unsupported_file', 'file_unavailable', 'input_too_large', 'output_too_large', 'provider_failure', 'invalid_output', 'cancelled'];
+export type RoutineAIErrorCode = typeof ROUTINE_AI_ERROR_CODES[number];
+/** Safe failures contain only an allowlisted code, never provider payloads. */
+export declare class RoutineAIError extends Error {
+    readonly code: RoutineAIErrorCode;
+    constructor(code: RoutineAIErrorCode);
+}
+/** Private transports carry only the bounded failure code. */
+export declare function parseRoutineAIError(value: unknown): RoutineAIError;
+export type RoutineAIInput = string | File;
+export type RoutineAIRequest = {
+    kind: 'generateText';
+    instructions: string;
+    input: RoutineAIInput;
+} | {
+    kind: 'generateObject';
+    instructions: string;
+    input: RoutineAIInput;
+    schema: AppValueSchema;
+};
+export type RoutineAIResult = {
+    text: string;
+} | {
+    object: unknown;
+};
+export type RoutineAITransport = (request: RoutineAIRequest) => Promise<RoutineAIResult>;
+/** Inert schema grammar only. SDK builders must be resolved before transport. */
+export declare function parseRoutineAIRequest(value: unknown): RoutineAIRequest;
+/** Validate results again at delivery; provider text is never implicitly repaired. */
+export declare function parseRoutineAIResult(request: RoutineAIRequest, value: unknown): RoutineAIResult;
+/** Native adapters discard reasoning and pass only the final text here. */
+export declare function acceptRoutineAIOutput(request: RoutineAIRequest, text: unknown): RoutineAIResult;

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

@@ -2,7 +2,7 @@ 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 ai?: true;
     readonly files?: 'read' | 'read-write';
     readonly publish?: readonly ('asks' | 'digests')[];
 };

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

@@ -11,7 +11,7 @@ export type RoutineDeclaration = {
     access: {
         repositories: Record<string, 'read' | 'write'>;
         connections: string[];
-        models: string[];
+        ai?: true;
         files?: 'read' | 'read-write';
         publish: Array<'asks' | 'digests'>;
     };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oddington/sdk",
-  "version": "0.1.23",
-  "description": "Oddington routine and response-handler SDK",
+  "version": "0.1.25",
+  "description": "OS routine and response-handler SDK",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "files": ["dist", "LICENSE", "README.md"],