@oddington/sdk 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,47 @@
+import type { AskInput, CapturedRecords, DigestInput, InboxFile, PublicationRequest, PublishedAsk, PublishedDigest, RepositoryReceipt, ResolutionInput } from '../../../shared/inbox-contract.js';
+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 * from '../../../shared/inbox-contract.js';
+export * from '../../../shared/inbox-views.js';
+export { RoutineRecordWriteError } from '../../../shared/record-write.js';
+export type InboxRequester = (path: string, init?: RequestInit) => Promise<Response>;
+export type RoutinePublicationClientOptions = {
+    workspace?: string;
+    capability?: string;
+    request?: InboxRequester;
+    workingRoot?: string;
+};
+export type RoutinePublicationClient = {
+    publishAsk(value: AskInput, options: {
+        requestKey: string;
+    }): Promise<PublishedAsk>;
+    publishDigest(value: DigestInput, options: {
+        requestKey: string;
+    }): Promise<PublishedDigest>;
+    publishResolution(askId: string, value: ResolutionInput): Promise<void>;
+    readRecords(input: RecordReadInput): Promise<CapturedRecords>;
+    repository: {
+        readRecords(input: RecordReadInput): Promise<CapturedRecords>;
+        updateRecords(input: RecordUpdateRequest, options: {
+            requestKey: string;
+        }): Promise<{
+            receipt: RepositoryReceipt;
+        }>;
+        writeRecords(input: RecordWriteRequest, options: {
+            requestKey: string;
+        }): Promise<{
+            receipt: RepositoryReceipt;
+        }>;
+        deleteRecords(input: RecordDeleteRequest, options: {
+            requestKey: string;
+        }): Promise<{
+            receipt: RepositoryReceipt;
+        }>;
+    };
+    files: {
+        add(value: FileAddOptions): Promise<InboxFile>;
+    };
+    check(body: PublicationRequest): Promise<void>;
+};
+export declare function routinePublicationClient(options?: RoutinePublicationClientOptions): RoutinePublicationClient;

package/dist/types/shared/delimited-text.d.ts

@@ -0,0 +1,2 @@
+export declare function parseDelimitedText(value: string, declaredDelimiter?: string): string[][];
+export declare function delimitedDataRowCount(rows: string[][], headerRow?: number): number;

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

@@ -0,0 +1,366 @@
+/** The bounded ask/digest contract. Authorization and durable effects belong to
+ * the server; constructing a value here grants no publication authority. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject;
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+export type AuthoredSource = {
+    type: 'authored';
+    options: Array<{
+        value: string;
+        label: string;
+        description?: string;
+        note?: {
+            placeholder: string;
+        };
+    }>;
+    suggestions?: string[];
+    search?: {
+        triggerLabel: string;
+        placeholder: string;
+        emptyLabel: string;
+    };
+};
+export type RecordReference = {
+    repository: string;
+    ref: string;
+};
+export type RecordSource = {
+    type: 'records';
+    collection: {
+        repository: string;
+        name: string;
+    };
+    refPrefix?: string;
+    where?: Record<string, string | number | boolean | null>;
+    display: {
+        labelFields: string[];
+    };
+    suggestions?: Array<{
+        record: RecordReference;
+        reason?: string;
+    }>;
+};
+export type ResponseDefinition = {
+    type: 'selection';
+    source: AuthoredSource | RecordSource;
+};
+export type QuestionResponse = {
+    selection: string | RecordReference;
+    note?: string;
+};
+export type HandlerReference = {
+    id: string;
+    input: JsonValue;
+};
+export type Question = {
+    id: string;
+    to: string;
+    allowedResponders: string[];
+    prompt: string;
+    instructions?: string;
+    response: ResponseDefinition;
+    handler?: HandlerReference;
+};
+export type QuestionInput = Omit<Question, 'allowedResponders'> & {
+    allowedResponders?: string[];
+};
+export type PublishedView = {
+    id: string;
+    view: string;
+    input: JsonValue;
+};
+export type PresentedField = {
+    label: string;
+    value: string;
+};
+export type PresentedRecord = {
+    ref: string;
+    title: string;
+    fields: PresentedField[];
+};
+export type PresentedRecordSummary = {
+    ref: string;
+    title: string;
+    description?: string;
+    facts?: PresentedField[];
+    view?: string;
+};
+export type CsvDetails = {
+    kind: 'csv';
+    encoding: 'utf-8' | 'windows-1252';
+    delimiter: ',' | ';' | '\t';
+    headerRow: number;
+    dataRows: number;
+};
+export type InboxFile = {
+    id: string;
+    name: string;
+    mediaType: string;
+    size: number;
+    sha256: string;
+    details: CsvDetails | {
+        kind: 'pdf';
+        pages?: number;
+    } | {
+        kind: 'other';
+    };
+};
+export type InboxBlock = {
+    kind: 'rich-text';
+    markdown: string;
+} | {
+    kind: 'record';
+    label: string;
+    record: PresentedRecord;
+    view?: string;
+    initiallyExpanded?: boolean;
+} | {
+    kind: 'records';
+    label: string;
+    records: PresentedRecordSummary[];
+    view?: string;
+    initiallyExpanded?: boolean;
+} | {
+    kind: 'files';
+    label: string;
+    files: InboxFile[];
+    initiallyExpanded?: boolean;
+} | {
+    kind: 'asks';
+    problem: string;
+    asks: string[];
+};
+type Presentation = {
+    title: string;
+    description: string;
+    views?: PublishedView[];
+    body?: InboxBlock[];
+    notifyImmediately?: boolean;
+};
+export type AskInput = Presentation & {
+    recipients?: string[];
+    questions?: QuestionInput[];
+};
+export type DigestInput = Presentation & {
+    recipients: string[];
+};
+export type AskPublication = Presentation & {
+    kind: 'ask';
+    recipients: string[];
+    questions: Question[];
+};
+export type DigestPublication = DigestInput & {
+    kind: 'digest';
+};
+export type Publication = AskPublication | DigestPublication;
+export type RecipientPublication = DigestPublication | (Omit<AskPublication, 'questions'> & {
+    questions: Array<Omit<Question, 'handler'>>;
+});
+/** These values are supplied by the verified launch/storage path, never by an
+ * authored item. They are separate from recipient-facing presentation. */
+export type PublisherProvenance = {
+    workspaceId: string;
+} & ({
+    personId: string;
+} | {
+    routineId: string;
+    runId: string;
+    routineVersion: string;
+});
+export type RetainedPublication = {
+    id: string;
+    revision: 1;
+    publisher: PublisherProvenance;
+    /** Internal retained definition, including private handler input. Never send
+     * this object directly to a recipient; use recipientPresentation. */
+    presentation: Publication;
+    resolvedViews: Array<{
+        id: string;
+        implementation: string;
+    }>;
+};
+export type QuestionInstance = {
+    askId: string;
+    revision: number;
+    questionId: string;
+};
+export type ResponseSubmission = QuestionInstance & {
+    response: QuestionResponse;
+};
+export type OddingtonAssignment = {
+    type: 'oddington';
+    reason: string;
+};
+export type Resolution = {
+    outcome: string;
+    evidence?: JsonValue[];
+};
+export type HandlerTransition = {
+    type: 'continue';
+    assignTo?: OddingtonAssignment;
+} | ({
+    type: 'resolve';
+} & Resolution);
+export type ResolutionInput = Resolution & {
+    expectedRevision: number;
+};
+export type CapturedRecords = {
+    commit: string;
+    records: Array<{
+        ref: string;
+        version: string;
+        fields: JsonObject;
+    }>;
+};
+export type RecordUpdate = {
+    ref: string;
+    expectedVersion: string;
+    set: JsonObject;
+};
+export type RecordCreate = {
+    ref: string;
+    path: string;
+    fields: JsonObject;
+};
+export type RecordDelete = {
+    ref: string;
+    expectedVersion: string;
+};
+export type RepositoryReceipt = {
+    repository: string;
+    commit: string;
+    diff: string;
+};
+export interface RepositoryCapabilities {
+    readRecords(input: {
+        repository: string;
+        refs: string[];
+        atCommit?: string;
+    }): Promise<CapturedRecords>;
+    writeRecords(input: {
+        repository: string;
+        records: Array<RecordCreate | RecordUpdate>;
+    }): Promise<{
+        receipt: RepositoryReceipt;
+    }>;
+    updateRecords(input: {
+        repository: string;
+        records: RecordUpdate[];
+    }): Promise<{
+        receipt: RepositoryReceipt;
+    }>;
+    deleteRecords(input: {
+        repository: string;
+        records: RecordDelete[];
+    }): Promise<{
+        receipt: RepositoryReceipt;
+    }>;
+}
+export type HandlerRuntime<Input extends JsonValue = JsonValue> = {
+    input: Input;
+    response: QuestionResponse;
+    ask: {
+        readonly id: string;
+        readonly revision: number;
+        viewInput(id: string): JsonValue;
+    };
+    responseDefinition: ResponseDefinition;
+    questionId: string;
+    repository: RepositoryCapabilities;
+};
+export type Handler<Input extends JsonValue = JsonValue> = {
+    id: string;
+    run(runtime: HandlerRuntime<Input>): Promise<HandlerTransition>;
+};
+export declare class InboxContractError extends Error {
+    constructor(message: string);
+}
+/** Copy only lossless JSON. In particular, JSON.stringify must not silently
+ * erase undefined/functions or convert dates, sparse arrays, or nonfinite numbers. */
+export declare function serializable(value: unknown, ancestors?: Set<object>): JsonValue;
+export declare function validateInboxFile(value: unknown): InboxFile;
+export declare function validateBlock(value: unknown): InboxBlock;
+export declare function richTextBlock(value: Omit<Extract<InboxBlock, {
+    kind: 'rich-text';
+}>, 'kind'>): Extract<InboxBlock, {
+    kind: 'rich-text';
+}>;
+export declare function recordBlock(value: Omit<Extract<InboxBlock, {
+    kind: 'record';
+}>, 'kind'>): Extract<InboxBlock, {
+    kind: 'record';
+}>;
+export declare function recordsBlock(value: Omit<Extract<InboxBlock, {
+    kind: 'records';
+}>, 'kind'>): Extract<InboxBlock, {
+    kind: 'records';
+}>;
+export declare function fileBlock(value: Omit<Extract<InboxBlock, {
+    kind: 'files';
+}>, 'kind'>): Extract<InboxBlock, {
+    kind: 'files';
+}>;
+export declare function asksBlock(value: Omit<Extract<InboxBlock, {
+    kind: 'asks';
+}>, 'kind'>): Extract<InboxBlock, {
+    kind: 'asks';
+}>;
+export declare function selection(value: {
+    source: AuthoredSource | RecordSource;
+}): ResponseDefinition;
+export declare function validateRecordReference(value: unknown): RecordReference;
+export declare function validateRecordSource(value: unknown): RecordSource;
+export declare function validateResponseDefinition(value: unknown): ResponseDefinition;
+export declare function validateResponse(definition: unknown, value: unknown): QuestionResponse;
+export declare function defineHandler<Input extends JsonValue>(value: Handler<Input>): Handler<Input>;
+export declare function respond<Input extends JsonValue>(handler: Handler<Input>, input: Input): HandlerReference;
+export declare function question(value: QuestionInput): Question;
+/** Structural validation is shared. Registered view/handler availability,
+ * people, repository/file access, and provenance MUST be checked by publication too. */
+export declare function validatePublication(value: unknown): Publication;
+/** Structural projection only. The read boundary must check current recipient,
+ * workspace and repository/file access before returning this content. */
+export declare function recipientPresentation(value: unknown): RecipientPublication;
+export declare function oddington(value: {
+    reason: string;
+}): OddingtonAssignment;
+export declare function continueAsk(value: {
+    assignTo?: OddingtonAssignment;
+}): HandlerTransition;
+export declare function resolveAsk(value: Resolution): HandlerTransition;
+/** Call at the durable transition boundary with server-derived remaining work,
+ * excluding the execution being completed. Lifecycle/effect guards also apply. */
+export declare function validateHandlerTransition(value: unknown, state: {
+    hasOtherViableWork: boolean;
+}): HandlerTransition;
+export declare function validateResolution(value: unknown): ResolutionInput;
+export type PublicationRequest = {
+    requestKey: string;
+    item: Publication;
+};
+export type PublishedAsk = {
+    id: string;
+    revision: number;
+};
+export type PublishedDigest = {
+    id: string;
+};
+/** The server verifies workspace membership and optional trusted run provenance. */
+export interface InboxPublicationTransport {
+    publish(request: PublicationRequest): Promise<PublishedAsk | PublishedDigest>;
+    resolve(request: {
+        askId: string;
+        resolution: ResolutionInput;
+    }): Promise<void>;
+}
+export declare function createInboxPublisher(transport: InboxPublicationTransport): {
+    publishAsk(value: AskInput, options: {
+        requestKey: string;
+    }): Promise<PublishedAsk>;
+    publishDigest(value: DigestInput, options: {
+        requestKey: string;
+    }): Promise<PublishedDigest>;
+    publishResolution(askId: string, value: ResolutionInput): Promise<void>;
+};
+export {};

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

@@ -0,0 +1,17 @@
+import { type InboxFile, type CsvDetails } from './inbox-contract.js';
+export type FileAddOptions = {
+    path: string;
+    name?: string;
+    csv?: {
+        encoding?: CsvDetails['encoding'];
+        delimiter?: CsvDetails['delimiter'];
+        headerRow?: number;
+    };
+};
+export declare function validateFileAddOptions(value: unknown): FileAddOptions;
+export declare function validateCsvHints(value: unknown): NonNullable<FileAddOptions['csv']>;
+export declare function csvRows(bytes: Uint8Array, details: CsvDetails): string[][];
+export declare function deriveInboxFile(bytes: Uint8Array, name: string, csv?: FileAddOptions['csv']): Promise<Omit<InboxFile, 'id'>>;
+/** Integrity/type checks apply to publication and every fresh download. */
+export declare function verifyInboxFile(bytes: Uint8Array, value: unknown): Promise<InboxFile>;
+export declare function publicationFiles(body?: import('./inbox-contract.js').InboxBlock[]): InboxFile[];

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

@@ -0,0 +1,97 @@
+import { type JsonObject, type PublishedView } from './inbox-contract.js';
+export type TableColumn = {
+    id: string;
+    label: string;
+    type: 'string' | 'date' | 'integer' | 'number' | 'boolean' | 'enum' | 'nullable-enum' | 'link';
+    unit?: string;
+    values?: string[];
+    missing: 'reject';
+    missingLabel?: string;
+};
+export type RecordTableInput = {
+    repository?: string;
+    commit?: string;
+    columns: TableColumn[];
+    rows: Array<{
+        ref: string;
+        version?: string;
+        values: JsonObject;
+    }>;
+    /** Routine-owned evidence (such as batch relationships), never interpreted by the host. */
+    metadata?: JsonObject;
+};
+export type CapturedRecordTableInput = Omit<RecordTableInput, 'repository' | 'commit' | 'rows'> & {
+    repository: string;
+    commit: string;
+    rows: Array<{
+        ref: string;
+        version: string;
+        values: JsonObject;
+    }>;
+};
+export declare function validateCapturedRecordTableInput(value: unknown): CapturedRecordTableInput;
+export type ResolvedView = PublishedView & {
+    implementation: string;
+};
+export type RecordValue = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'missing';
+    label: string;
+} | {
+    kind: 'record';
+    ref: string;
+    label: string;
+    recordType?: string;
+} | {
+    kind: 'list';
+    items: RecordValue[];
+    remaining?: number;
+} | {
+    kind: 'object';
+    fields: RecordField[];
+};
+export type RecordField = {
+    label: string;
+    value: RecordValue;
+};
+export type ViewRecord = {
+    ref: string;
+    title: string;
+    recordType?: string;
+    fields: RecordField[];
+    body?: {
+        label: string;
+        markdown: string;
+    };
+};
+export type RecordViewInput = {
+    record: ViewRecord;
+    related?: ViewRecord[];
+};
+export declare const commonViews: ({
+    name: string;
+    implementation: string;
+    workspaces: '*';
+    validate: typeof validateRecordViewInput;
+} | {
+    name: string;
+    implementation: string;
+    workspaces: '*';
+    validate: typeof validateRecordTableInput;
+})[];
+export declare function validateRecordViewInput(value: unknown): RecordViewInput;
+export declare function validateRecordTableInput(value: unknown): RecordTableInput;
+export declare const registeredViews: ({
+    name: string;
+    implementation: string;
+    workspaces: '*';
+    validate: typeof validateRecordViewInput;
+} | {
+    name: string;
+    implementation: string;
+    workspaces: '*';
+    validate: typeof validateRecordTableInput;
+})[];
+export declare function resolveInboxView(view: PublishedView, workspace: string): ResolvedView;

package/dist/types/shared/record-capture.d.ts

@@ -0,0 +1,7 @@
+import { type RepositoryCapabilities } from './inbox-contract.js';
+export type RecordReadInput = Parameters<RepositoryCapabilities['readRecords']>[0];
+export declare const RECORD_READ_INPUT_LIMIT: number;
+export declare const RECORD_CAPTURE_OUTPUT_LIMIT: number;
+export declare function validRecordRef(value: unknown): value is string;
+/** Only record selectors cross the customer boundary; destinations are trusted configuration. */
+export declare function validateRecordRead(value: unknown): RecordReadInput;

package/dist/types/shared/record-write.d.ts

@@ -0,0 +1,29 @@
+import { type RecordCreate, type RecordDelete, type RecordUpdate } from './inbox-contract.js';
+export type RecordWrite = RecordCreate | RecordUpdate;
+export type RecordUpdateRequest = {
+    repository: string;
+    records: RecordUpdate[];
+};
+export type RecordWriteRequest = {
+    repository: string;
+    records: RecordWrite[];
+};
+export type RecordDeleteRequest = {
+    repository: string;
+    records: RecordDelete[];
+};
+export type RecordChangeRequest = RecordWriteRequest | RecordDeleteRequest;
+export type RoutineRecordWriteRequest = {
+    input: RecordChangeRequest;
+    requestKey: string;
+};
+export declare const RECORD_WRITE_INPUT_LIMIT: number;
+export declare class RoutineRecordWriteError extends Error {
+    readonly effect: 'unapplied' | 'uncertain' | 'pending';
+    constructor(message: string, effect: 'unapplied' | 'uncertain' | 'pending');
+}
+export declare function validateRecordWrite(value: unknown): RecordWriteRequest;
+export declare function validateRecordUpdate(value: unknown): RecordUpdateRequest;
+export declare function validateRecordDelete(value: unknown): RecordDeleteRequest;
+export declare function validateRecordChange(value: unknown): RecordChangeRequest;
+export declare function validateRoutineRecordWrite(value: unknown): RoutineRecordWriteRequest;

package/dist/types/shared/repository-targets.d.ts

@@ -0,0 +1,22 @@
+/** Secret-free, workspace-member-visible GitHub repository destination. */
+export interface RepositoryTarget {
+    id: string;
+    workspaceId: string;
+    connectionId: string;
+    repository: string;
+    remote: string;
+    githubRepositoryId: number;
+    targetRef: string;
+    enabled: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Managed Git-tree data boundaries. */
+export interface RepositoryDataTarget extends RepositoryTarget {
+    dataRoots: string[];
+}
+export declare function validDataRoots(value: unknown): value is string[];
+export declare function parseRepositoryDataTarget(value: unknown): RepositoryDataTarget;
+export declare function validRepositoryAlias(value: unknown): value is string;
+export declare function validTargetRef(value: unknown): value is string;
+export declare function parseRepositoryTarget(value: unknown): RepositoryTarget;

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@oddington/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Oddington routine and response-handler SDK",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "files": ["dist", "LICENSE", "README.md"],
+  "engines": { "node": ">=22.12.0" },
+  "publishConfig": { "access": "public" },
+  "exports": {
+    ".": {
+      "types": "./dist/types/packages/sdk/src/public.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "bun run scripts/build.ts",
+    "check": "tsc --noEmit",
+    "prepack": "bun run scripts/prepack.ts",
+    "verify:package": "bun run scripts/verify-package.ts"
+  },
+  "devDependencies": {
+    "@types/node": "26.6.1",
+    "typescript": "7.0.2"
+  }
+}