@oddington/sdk 0.1.10 → 0.1.12

package/dist/types/packages/sdk/src/auth-types.d.ts

@@ -0,0 +1,40 @@
+export type BrowserAuthErrorReason = 'invalid_input' | 'invalid_code' | 'unavailable' | 'busy' | 'stale' | 'disposed';
+export type BrowserAuthorizationResult = Readonly<{
+    status: 'consent';
+    clientName: string;
+    account: Readonly<{
+        email: string;
+        displayName: string;
+    }>;
+    scopes: readonly string[];
+    callbackAddress: string;
+}> | Readonly<{
+    status: 'return';
+    returnUrl: string;
+}> | Readonly<{
+    status: 'missing' | 'expired' | 'unavailable' | 'invalid' | 'signed_out' | 'stale' | 'disposed' | 'busy';
+}>;
+export interface BrowserAuthorization {
+    get(id: string): Promise<BrowserAuthorizationResult>;
+    approve(id: string): Promise<BrowserAuthorizationResult>;
+    deny(id: string): Promise<BrowserAuthorizationResult>;
+}
+export type BrowserAuthState = Readonly<{
+    status: 'initializing' | 'signed_out' | 'signed_in' | 'expired' | 'unavailable';
+    account?: Readonly<{
+        email: string;
+        displayName: string;
+    }>;
+    pending?: 'send_code' | 'verify_code' | 'sign_out';
+    error?: BrowserAuthErrorReason;
+}>;
+/** An opaque browser capability. Provider configuration and sessions stay private. */
+export interface BrowserAuthHandle {
+    readonly authorization: BrowserAuthorization;
+    getState(): BrowserAuthState;
+    subscribe(listener: (state: BrowserAuthState) => void): () => void;
+    sendCode(email: string): Promise<void>;
+    verifyCode(email: string, code: string): Promise<void>;
+    signOut(): Promise<void>;
+    dispose(): void;
+}

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

@@ -2,6 +2,10 @@ 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 } 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;
 export { InboxContractError, asksBlock, continueAsk, defineHandler, fileBlock, question, recordBlock, recordsBlock, resolveAsk, respond, richTextBlock, selection, } from '../../../shared/inbox-contract.js';
 export type { AskInput, AuthoredSource, CapturedRecords, CsvDetails, DigestInput, Handler, HandlerReference, HandlerRuntime, HandlerTransition, InboxBlock, InboxFile, JsonObject, JsonValue, PresentedField, PresentedRecord, PresentedRecordSummary, PublishedAsk, PublishedDigest, PublishedView, PublicationRequest, Question, QuestionInput, QuestionResponse, RecordCreate, RecordDelete, RecordReference, RecordSource, RecordUpdate, RepositoryCapabilities, RepositoryReceipt, Resolution, ResolutionInput, ResponseDefinition, } from '../../../shared/inbox-contract.js';
 export type { CapturedRecordTableInput, RecordField, RecordTableInput, RecordValue, RecordViewInput, TableColumn, ViewRecord, } from '../../../shared/inbox-views.js';
@@ -13,7 +17,7 @@ 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 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, 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, 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;
 };
@@ -22,6 +26,7 @@ export type { File, FileInput, FileStorage, FileCreateInput, FileCreateOptions,
 export declare const files: {
     create(input: import('../../../shared/files-contract.js').FileCreateInput, options?: import('../../../shared/files-contract.js').FileCreateOptions): Promise<import('../../../shared/files-contract.js').File>;
     get(id: string): Promise<import('../../../shared/files-contract.js').File>;
+    delete(id: string): Promise<void>;
     upload(id: string): Promise<import('../../../shared/files-contract.js').File>;
     enrich(input: import('../../../shared/files-contract.js').FileEnrichOptions): Promise<import('../../../shared/files-contract.js').FileEnrichResult>;
     read(id: string): Promise<Response>;
@@ -61,9 +66,17 @@ export type HostedSessionSource = {
 /** OS-owned hosted or exact-origin local browser bootstrap. Reinitialization replaces the context. */
 export declare const os: {
     init(options: {
-        auth: HostedSessionSource;
+        auth: HostedSessionSource | import('./auth-types.js').BrowserAuthHandle;
     }): void;
 };
+export type { BrowserAuthHandle, BrowserAuthState, BrowserAuthErrorReason, BrowserAuthorization, BrowserAuthorizationResult } from './auth-types.js';
+export declare class BrowserAuthError extends Error {
+    readonly reason: import('./auth-types.js').BrowserAuthErrorReason;
+    constructor(reason: import('./auth-types.js').BrowserAuthErrorReason);
+}
+export declare const auth: {
+    create(): import('./auth-types.js').BrowserAuthHandle;
+};
 /** Customer-owned module augmentation supplies types, never runtime authority. */
 export interface AppRoutineTypes {
 }

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

@@ -0,0 +1,56 @@
+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 { DataRepository } from '../../../shared/data-contract.js';
+import type { files, RoutinePublicationClient } from './public.js';
+declare const valueType: unique symbol;
+/** Serializable declaration; the phantom type never carries authority. */
+export type RoutineSchema<Value> = AppValueSchema & {
+    readonly [valueType]?: Value;
+};
+export type RoutineSchemaValue<Schema> = Schema extends RoutineSchema<infer Value> ? Value : undefined;
+export type RoutineSteps = Record<string, RoutineSchema<unknown> | null>;
+export type RoutineInput<Value> = Value extends object ? {
+    readonly [Key in keyof Value]: RoutineInput<Value[Key]>;
+} : Value;
+export type RoutineRuntime<Steps extends RoutineSteps> = {
+    readonly run: {
+        readonly id: string;
+    };
+    readonly data: {
+        repository(name: string): DataRepository;
+    };
+    readonly files: typeof files;
+    readonly connections: Connections;
+    readonly inbox: RoutinePublicationClient;
+    step<Key extends Extract<keyof Steps, string>>(id: Key, ...summary: Steps[Key] extends null ? [] : [summary: RoutineSchemaValue<Steps[Key]>]): Promise<void>;
+};
+export type RoutineDefinition<Input extends RoutineSchema<unknown> | undefined, Steps extends RoutineSteps, Result extends RoutineSchema<unknown> | undefined> = {
+    readonly input?: Input;
+    readonly steps?: Steps;
+    readonly result?: Result;
+    readonly run: (input: RoutineInput<Input extends undefined ? Record<string, never> : RoutineSchemaValue<Input>>, os: RoutineRuntime<Steps>) => Result extends undefined ? void | Promise<void> : RoutineSchemaValue<Result> | Promise<RoutineSchemaValue<Result>>;
+};
+export type DefineRoutine = <Input extends RoutineSchema<unknown> | undefined = undefined, const Steps extends RoutineSteps = {}, Result extends RoutineSchema<unknown> | undefined = undefined>(definition: RoutineDefinition<Input, Steps, Result>) => RoutineDefinition<Input, Steps, Result>;
+export type RoutineSchemaBuilders = {
+    object<const Properties extends Record<string, RoutineSchema<unknown>>>(properties: Properties): RoutineSchema<{
+        [Key in keyof Properties]: RoutineSchemaValue<Properties[Key]>;
+    }>;
+    array<Item extends RoutineSchema<unknown>>(items: Item, options: {
+        maxItems: number;
+    }): RoutineSchema<RoutineSchemaValue<Item>[]>;
+    string(options?: {
+        maxLength?: number;
+    }): RoutineSchema<string>;
+    integer(options?: {
+        minimum?: number;
+        maximum?: number;
+    }): RoutineSchema<number>;
+    number(options?: {
+        minimum?: number;
+        maximum?: number;
+    }): RoutineSchema<number>;
+    boolean(): RoutineSchema<boolean>;
+};
+export type RoutineFileSchema = () => RoutineSchema<File>;
+export {};

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

@@ -0,0 +1,43 @@
+export type AppValueSchema = {
+    type: 'object';
+    properties: Record<string, AppValueSchema>;
+    required?: string[];
+    additionalProperties: false;
+} | {
+    type: 'array';
+    items: AppValueSchema;
+    maxItems: number;
+} | {
+    type: 'boolean';
+} | {
+    type: 'string';
+    maxLength?: number;
+} | {
+    type: 'integer' | 'number';
+    minimum?: number;
+    maximum?: number;
+} | {
+    type: 'file';
+};
+export type AppRoutineContract = {
+    routine: string;
+    input: AppValueSchema;
+    steps: {
+        id: string;
+        summary?: AppValueSchema;
+    }[];
+    result?: AppValueSchema;
+};
+/** Bounded diagnostics never echo authored values, names or paths. */
+export declare class AppRoutineContractError extends Error {
+    readonly code: 'invalid_contract' | 'invalid_value';
+    constructor(code: 'invalid_contract' | 'invalid_value');
+}
+/** One operation owns the property budget across input, result and all summaries. */
+export declare function parseAppRoutineContract(value: unknown): AppRoutineContract;
+export declare function validateRoutineSchemaValue(schema: AppValueSchema, value: unknown): void;
+/** Structural validation grants no execution or File-use authority. Values stay unchanged. */
+export declare function validateAppRoutineInput(contract: AppRoutineContract, value: unknown): void;
+export declare function validateAppRoutineResult(contract: AppRoutineContract, value?: unknown): void;
+/** Validates only the declared projection; report/event envelopes belong to the runtime. */
+export declare function validateAppRoutineStep(contract: AppRoutineContract, id: string, summary?: unknown): void;

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

@@ -138,6 +138,14 @@ export type HistoryListOptions = {
     limit?: number;
     before?: string;
 };
+export type HistoryChangesOptions = {
+    collections?: string[];
+    refs?: string[];
+    from?: string;
+    through?: string;
+    limit?: number;
+    after?: string;
+};
 export type HistoryEntry = {
     version: string;
     publishedAt: string;
@@ -156,6 +164,19 @@ export type HistoryEntry = {
     updated: string[];
     deleted: string[];
 };
+export type HistoryChange = Omit<HistoryEntry, 'created' | 'updated' | 'deleted'> & {
+    $ref: string;
+    change: 'created' | 'updated' | 'deleted';
+    before: SelectedRecord | null;
+    after: SelectedRecord | null;
+};
+export type HistoryChangesResult = {
+    $meta: {
+        through: string;
+        next?: string;
+    };
+    changes: HistoryChange[];
+};
 export interface DataChangeSet {
     create(record: RecordCreation): void;
     update(record: RecordIdentity, set: RecordUpdateSet): void;
@@ -175,6 +196,7 @@ export interface DataRepository {
     history: {
         list(options?: HistoryListOptions): Promise<HistoryEntry[]>;
         at(instant: string): Promise<HistoryEntry | null>;
+        changes(options?: HistoryChangesOptions): Promise<HistoryChangesResult>;
     };
     changes(): DataChangeSet;
 }

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

@@ -82,7 +82,15 @@ export type FileCreateMetadata = {
     path: string;
     storage?: FileStorage;
     csv?: Required<FileCsvHints>;
+    inputMediaType?: 'application/pdf';
     size: number;
     requestKey: string;
 };
+/** A declared PDF is descriptive metadata; this rule never reads original bytes. */
+export declare function declaredOriginalFormat(input: Pick<FileCreateMetadata, 'name' | 'inputMediaType'>): {
+    mediaType: 'application/pdf';
+    details: {
+        kind: 'pdf';
+    };
+} | undefined;
 export declare function parseFileCreateMetadata(value: unknown, maxBytes: number): FileCreateMetadata;

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

@@ -267,6 +267,7 @@ export type HandlerRuntime<Input extends JsonValue = JsonValue> = {
 };
 export type Handler<Input extends JsonValue = JsonValue> = {
     id: string;
+    results?: readonly string[];
     run(runtime: HandlerRuntime<Input>): Promise<HandlerTransition>;
 };
 export declare class InboxContractError extends Error {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oddington/sdk",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Oddington routine and response-handler SDK",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
@@ -22,6 +22,7 @@
     "verify:package": "bun run scripts/verify-package.ts"
   },
   "devDependencies": {
+    "@supabase/auth-js": "2.116.0",
     "@types/node": "26.6.1",
     "esbuild": "0.28.1",
     "typescript": "7.0.2"