@oddington/sdk 0.1.44 → 0.1.45

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

@@ -6,8 +6,8 @@ export declare const file: import('./routine-definition-types.js').RoutineFileSc
 export { AIError, RoutineAIError } from '../../../shared/routine-ai-contract.js';
 export type { RoutineAIOutputIssue } from '../../../shared/routine-ai-output-detail.js';
 export type { RoutineAIErrorDetail } from '../../../shared/routine-ai-error-detail.js';
-export { InboxContractError, asksBlock, continueAsk, defineHandler, fileBlock, question, recordBlock, recordsBlock, resolveAsk, respond, richTextBlock, selection, } from '../../../shared/inbox-contract.js';
-export type { AskInput, AuthoredSource, CapturedRecords, 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 { InboxContractError, asksBlock, continueAsk, defineHandler, fileBlock, question, recordBlock, recordsBlock, requireRecords, resolveAsk, respond, richTextBlock, selection, } from '../../../shared/inbox-contract.js';
+export type { AskInput, AuthoredSource, CapturedRecords, DigestInput, Handler, HandlerReference, HandlerRuntime, HandlerTransition, InboxBlock, InboxFile, JsonObject, JsonValue, PresentedField, PresentedRecord, PresentedRecordSummary, PublishedAsk, PublishedDigest, PublishedView, PublicationRequest, Question, QuestionInput, QuestionResponse, RecordCreate, RecordDelete, RecordReference, RecordRequirements, 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';
 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';
@@ -33,7 +33,7 @@ export { FileOperationError } from '../../../shared/files-contract.js';
 export { source } from './source.js';
 export type { SourceLocation, OsSourceLocation, GmailSourceLocation, DropboxSourceLocation, OutlookSourceLocation, SharePointSourceLocation } from './source.js';
 export { InboxOperationError } from '../../../shared/inbox-member-contract.js';
-export type { InboxMember, InboxCurrent, InboxItem, AnswerableQuestion, QuestionSnapshot, ResponseConsequence, LinkedAskSnapshot, AskUpdate, DigestReadConfirmation, RecipientCandidate, RecipientAddition, ResponseAcceptance, InboxAnswerInput, InboxSearchInput } from '../../../shared/inbox-member-types.js';
+export type { InboxMember, InboxCurrent, InboxItem, AnswerableQuestion, QuestionSnapshot, QuestionAvailability, QuestionUnavailableReason, ResponseConsequence, LinkedAskSnapshot, AskUpdate, DigestReadConfirmation, RecipientCandidate, RecipientAddition, ResponseAcceptance, InboxAnswerInput, InboxSearchInput } from '../../../shared/inbox-member-types.js';
 export type { RecordSelectionResult } from '../../../shared/record-selection.js';
 export declare const inbox: import('../../../shared/inbox-member-types.js').InboxMember;
 export type { File, FileInput, FileStorage, FileCreateInput, FileCreateOptions, FileEnrichment, FileEnrichOptions, FileEnrichResult, FileErrorCode, FileErrorDetail } from '../../../shared/files-contract.js';

package/dist/types/shared/connections.d.ts

@@ -0,0 +1,81 @@
+/** Public connection metadata only. No credentials, Vault references, or signers. */
+export type ConnectionProvider = 'github' | 'gmail' | 'airtable' | 'dropbox' | 'outlook' | 'sharepoint';
+export interface ConnectionConfig {
+    github: {
+        installationId: number;
+        accountId: number;
+        accountLogin: string;
+    };
+    gmail: {
+        accountEmail: string;
+        clientId: string;
+        scopes: string[];
+    };
+    airtable: {
+        baseId: string;
+    };
+    dropbox: {
+        accountId: string;
+        appKey: string;
+        scopes: string[];
+    } & DropboxRoot;
+    outlook: {
+        tenantId: string;
+        clientId: string;
+        mailboxEmail: string;
+        access?: string;
+    };
+    sharepoint: {
+        tenantId: string;
+        clientId: string;
+        siteUrl: string;
+        siteId: string;
+        access?: string;
+    };
+}
+export type DropboxRoot = {
+    access: 'app_folder';
+    rootIdentity: string;
+} | {
+    access: 'full_dropbox';
+    rootPath: string;
+};
+export type DropboxAuthorization = {
+    access: 'app_folder';
+} | {
+    access: 'full_dropbox';
+    rootPath: string;
+};
+/** An explicit existing folder, never the whole account or an ambiguous path. */
+export declare function validDropboxRootPath(value: unknown): value is string;
+export type Connection = {
+    [P in ConnectionProvider]: {
+        id: string;
+        workspaceId: string;
+        provider: P;
+        name: string;
+        config: ConnectionConfig[P];
+        enabled: boolean;
+        hasCredentials: boolean;
+        createdAt: string;
+        updatedAt: string;
+    };
+}[ConnectionProvider];
+/** Descriptive metadata only; Microsoft grants determine effective authority. */
+export declare function validMicrosoftAccess(value: unknown): value is string;
+/** Entra identifiers are GUID-form strings, including the documented example IDs. */
+export declare function validMicrosoftId(value: unknown): value is string;
+export declare function validMicrosoftMailbox(value: unknown): value is string;
+/** One spelling for saved and verified URLs; refuse ambiguity before URL normalization. */
+export declare function canonicalSharePointSiteUrl(value: unknown): string | undefined;
+export declare function validSharePointSiteId(value: unknown, siteUrl: string): value is string;
+/** Explicit Google scope identifiers, not a permission policy or read-only default. */
+export declare function validGoogleScopes(value: unknown): value is string[];
+export declare function validConnectionConfig(provider: unknown, value: unknown): boolean;
+/** Stable authorization root, independent of the human-visible App Folder name.
+ * App Folder mode must come from verified backend app registration, never input
+ * from a routine. Account home/team namespace IDs are not App Folder identities. */
+export declare function dropboxAppFolderIdentity(appKey: string, accountId: string): string;
+export declare const DROPBOX_FILE_SCOPES: readonly ['account_info.read', 'files.metadata.read', 'files.content.read', 'files.content.write'];
+export declare function validDropboxFileScopes(value: unknown): value is string[];
+export declare function parseConnectionMetadata(value: unknown): Connection;

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

@@ -0,0 +1,23 @@
+import { type Connection } from './connections.js';
+import { type RepositoryTarget } from './repository-targets.js';
+/** Private, secret-free Data identity and its current GitHub source authority. */
+export type DataRepositoryBinding = Readonly<{
+    id: string;
+    workspaceId: string;
+    repository: string;
+    gitRepository: Readonly<RepositoryTarget>;
+    connection: Readonly<Extract<Connection, {
+        provider: 'github';
+    }> & {
+        config: Readonly<Extract<Connection, {
+            provider: 'github';
+        }>['config']>;
+    }>;
+}>;
+export declare function validDataRepositoryName(value: unknown): value is string;
+/** Detach all nested authority before asynchronous work. No caller-selected path. */
+export declare function parseDataRepositoryBinding(value: unknown): DataRepositoryBinding;
+export declare function sameDataRepositoryBinding(a: DataRepositoryBinding, b: DataRepositoryBinding): boolean;
+export declare function dataRepositoryAvailable(binding: DataRepositoryBinding): boolean;
+/** GitHub pilot adapter boundary; compiler helpers may consume derived roots. */
+export declare function dataRepositoryRoots(binding: DataRepositoryBinding): string[];

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

@@ -1,6 +1,7 @@
 /** The bounded ask/digest contract. Authorization and durable effects belong to
  * the server; constructing a value here grants no publication authority. */
 import { type File } from './files-contract.js';
+import type { RecordIdentity } from './data-contract.js';
 export type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject;
 export type JsonObject = {
     [key: string]: JsonValue;
@@ -54,6 +55,13 @@ export type HandlerReference = {
     id: string;
     input: JsonValue;
 };
+export type RecordRequirements = {
+    repository: string;
+    records: Array<{
+        ref: string;
+        version: string;
+    }>;
+};
 export type Question = {
     id: string;
     to: string;
@@ -62,6 +70,7 @@ export type Question = {
     instructions?: string;
     response: ResponseDefinition;
     handler?: HandlerReference;
+    requirements?: RecordRequirements;
 };
 export type QuestionInput = Omit<Question, 'allowedResponders'> & {
     allowedResponders?: string[];
@@ -151,7 +160,7 @@ export type DigestPublication = DigestInput & {
 };
 export type Publication = AskPublication | DigestPublication;
 export type RecipientPublication = DigestPublication | (Omit<AskPublication, 'questions'> & {
-    questions: Array<Omit<Question, 'handler'>>;
+    questions: Array<Omit<Question, 'handler' | 'requirements'>>;
 });
 /** These values are supplied by the verified launch/storage path, never by an
  * authored item. They are separate from recipient-facing presentation. */
@@ -168,8 +177,8 @@ 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. */
+    /** Internal retained definition, including private handler input and requirements.
+     * Never send this directly to a recipient; use recipientPresentation. */
     presentation: Publication;
     resolvedViews: Array<{
         id: string;
@@ -325,6 +334,9 @@ export declare function defineHandler<Input extends JsonValue, const Id extends
     id: Id;
 };
 export declare function respond<Input extends JsonValue>(handler: Handler<Input>, input: Input): HandlerReference;
+/** Declare private exact-version guards from ordinary Data results. No Record
+ * content or repository snapshot is copied, and this grants no Data authority. */
+export declare function requireRecords(repository: string, records: readonly RecordIdentity[]): RecordRequirements;
 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. */

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

@@ -1,9 +1,20 @@
-import type { InboxCurrent, InboxItem, AnswerableQuestion, ResponseAcceptance } from './inbox-member-types.js';
+import type { InboxCurrent, InboxItem, AnswerableQuestion, ResponseAcceptance, QuestionAvailability, QuestionUnavailableReason } from './inbox-member-types.js';
 export declare class InboxOperationError extends Error {
     readonly status: number;
-    readonly reason: 'invalid_input' | 'access_denied' | 'authority_unavailable' | 'conflict' | 'unavailable';
-    constructor(status: number, reason: 'invalid_input' | 'access_denied' | 'authority_unavailable' | 'conflict' | 'unavailable');
+    readonly reason: 'invalid_input' | 'access_denied' | 'authority_unavailable' | 'conflict' | 'unavailable' | QuestionUnavailableReason;
+    readonly requirementsRepository?: string | undefined;
+    constructor(status: number, reason: 'invalid_input' | 'access_denied' | 'authority_unavailable' | 'conflict' | 'unavailable' | QuestionUnavailableReason, requirementsRepository?: string | undefined);
 }
+/** Closed recipient-safe state shared by snapshots and refusal transports. */
+export declare function parseQuestionAvailability(value: unknown, available?: boolean): QuestionAvailability;
+export declare function questionAvailability(value: QuestionAvailability, available?: boolean): QuestionAvailability;
+/** Only this exact safe envelope can carry an actionable acceptance refusal. */
+export declare function parseInboxUnavailableFailure(value: unknown, status: number): InboxOperationError | undefined;
+export declare function inboxErrorBody(error: InboxOperationError): {
+    error: string;
+    unavailableReason?: "access_denied" | "authority_unavailable" | "conflict" | "invalid_input" | "unavailable" | QuestionUnavailableReason | undefined;
+    requirementsRepository?: string | undefined;
+};
 export declare const INBOX_RESULT_BYTES: number;
 export declare const INBOX_INPUT_BYTES = 8192;
 /** Includes the exact declaration only on the private CLI-authenticated ingress. */

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

@@ -23,7 +23,12 @@ export interface ResponseConsequence {
     needsReconciliation: boolean;
     reason: string | null;
 }
-export interface QuestionSnapshot {
+export type QuestionUnavailableReason = 'handler_unavailable' | 'records_need_attention' | 'records_unavailable';
+export interface QuestionAvailability {
+    unavailableReason?: QuestionUnavailableReason;
+    requirementsRepository?: string;
+}
+export interface QuestionSnapshot extends QuestionAvailability {
     id: string;
     to: string;
     prompt: string;
@@ -127,7 +132,7 @@ export interface ResponseAcceptance {
     label?: string;
     acceptanceOrder?: number;
 }
-export interface AnswerableQuestion {
+export interface AnswerableQuestion extends QuestionAvailability {
     itemId: string;
     /** Parent Ask's workspace-scoped Inbox number, stable across revisions. */
     number: number;

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

@@ -1,4 +1,4 @@
-import { type RecordSource, type RecordReference } from './inbox-contract.js';
+import { InboxContractError, type RecordSource, type RecordReference } from './inbox-contract.js';
 export type RecordSelectionInput = {
     source: RecordSource;
     query: string;
@@ -18,4 +18,14 @@ export type RecordSelectionResult = {
     }>;
     selected?: LabeledRecord;
 };
+declare const selectionProblems: readonly ['collection_unavailable', 'display_fields_invalid', 'filter_fields_invalid', 'ref_prefix_invalid', 'suggestion_unavailable', 'selected_record_unavailable', 'label_unavailable'];
+export type RecordSelectionProblem = typeof selectionProblems[number];
+export declare function isRecordSelectionProblem(value: unknown): value is RecordSelectionProblem;
+/** Only these known definition failures cross the private Data boundary.
+ * Record values, provider errors and credentials never enter the envelope. */
+export declare class RecordSelectionError extends InboxContractError {
+    readonly problem: RecordSelectionProblem;
+    constructor(problem: RecordSelectionProblem, source: RecordSource);
+}
 export declare function validateRecordSelectionInput(value: unknown): RecordSelectionInput;
+export {};

package/package.json

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