@oddington/sdk 0.1.22 → 0.1.24

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

@@ -14,10 +14,12 @@ 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';
+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;
 };
@@ -183,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

@@ -1,6 +1,7 @@
 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';
@@ -59,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: RoutineStepInput<Steps[Key]> | 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;
@@ -98,4 +106,6 @@ export type RoutineSchemaBuilders = {
     }): RoutineSchema<number, false>;
     boolean(): RoutineSchema<boolean, false>;
 };
-export type RoutineFileSchema = () => RoutineSchema<File, false>;
+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/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/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-types.d.ts

@@ -63,12 +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;
@@ -105,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;
@@ -127,6 +138,7 @@ export interface AnswerableQuestion {
     instructions?: string;
     response: ResponseDefinition;
     answerable: boolean;
+    tags: string[];
     recordRefs: Array<{
         repository: string;
         id: string;
@@ -194,3 +206,4 @@ export interface InboxMember {
         }): Promise<Response>;
     };
 }
+export {};

package/package.json

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