@lssm/lib.contracts-spec 17.3.2

package/dist/registry-utils.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Registry utilities for filtering and grouping ContractSpec items.
+ * Provides shared logic used across all registry types.
+ */
+import type { Stability } from './ownership.js';
+/**
+ * Filter criteria for registry items.
+ * All criteria are optional and combined with AND logic.
+ */
+export interface RegistryFilter {
+    /** Filter by tags (item must have at least one matching tag) */
+    tags?: string[];
+    /** Filter by owners (item must have at least one matching owner) */
+    owners?: string[];
+    /** Filter by stability levels */
+    stability?: Stability[];
+    /** Filter by domain (first segment of name) */
+    domain?: string;
+    /** Filter by key pattern (glob or regex) */
+    keyPattern?: string;
+}
+/**
+ * Item with standard metadata for filtering.
+ */
+export interface FilterableItem {
+    meta: {
+        key?: string;
+        tags?: string[];
+        owners?: string[];
+        stability?: Stability;
+        domain?: string;
+    };
+}
+/**
+ * Grouping key function type.
+ */
+export type GroupKeyFn<T> = (item: T) => string;
+/**
+ * Grouped items result.
+ */
+export interface GroupedItems<T> {
+    key: string;
+    items: T[];
+}
+/**
+ * Pre-built grouping strategies for common use cases.
+ */
+export declare const GroupingStrategies: {
+    /**
+     * Group by first tag.
+     */
+    byTag: <T extends FilterableItem>(item: T) => string;
+    /**
+     * Group by all tags (item appears in multiple groups).
+     */
+    byAllTags: <T extends FilterableItem>(item: T) => string[];
+    /**
+     * Group by first owner.
+     */
+    byOwner: <T extends FilterableItem>(item: T) => string;
+    /**
+     * Group by domain (first segment of name).
+     */
+    byDomain: <T extends FilterableItem>(item: T) => string;
+    /**
+     * Group by stability level.
+     */
+    byStability: <T extends FilterableItem>(item: T) => string;
+    /**
+     * Create URL path grouping strategy with configurable depth.
+     */
+    byUrlPath: (level: number) => (item: {
+        path?: string;
+    }) => string;
+};
+/**
+ * Filter items by criteria.
+ * All criteria are combined with AND logic.
+ */
+export declare function filterBy<T extends FilterableItem>(items: T[], filter: RegistryFilter): T[];
+/**
+ * Group items by key function.
+ */
+export declare function groupBy<T>(items: T[], keyFn: GroupKeyFn<T>): Map<string, T[]>;
+/**
+ * Group items by key function, returning array format.
+ */
+export declare function groupByToArray<T>(items: T[], keyFn: GroupKeyFn<T>): GroupedItems<T>[];
+/**
+ * Group items where one item can belong to multiple groups.
+ * Useful for byAllTags grouping.
+ */
+export declare function groupByMultiple<T>(items: T[], keysFn: (item: T) => string[]): Map<string, T[]>;
+/**
+ * Get unique tags from a collection of items.
+ */
+export declare function getUniqueTags<T extends FilterableItem>(items: T[]): string[];
+/**
+ * Get unique owners from a collection of items.
+ */
+export declare function getUniqueOwners<T extends FilterableItem>(items: T[]): string[];
+/**
+ * Get unique domains from a collection of items.
+ */
+export declare function getUniqueDomains<T extends FilterableItem>(items: T[]): string[];

package/dist/registry-utils.js

@@ -0,0 +1 @@
+export const GroupingStrategies={byTag:(e)=>e.meta.tags?.[0]??"untagged",byAllTags:(e)=>e.meta.tags?.length?e.meta.tags:["untagged"],byOwner:(e)=>e.meta.owners?.[0]??"unowned",byDomain:(e)=>{return(e.meta.key??e.meta.key??"").split(".")[0]??"default"},byStability:(e)=>e.meta.stability??"stable",byUrlPath:(e)=>(t)=>{if(!t.path)return"root";return t.path.split("/").filter(Boolean).slice(0,e).join("/")||"root"}};export function filterBy(e,t){return e.filter((n)=>{if(t.tags?.length){if(!t.tags.some((s)=>n.meta.tags?.includes(s)))return!1}if(t.owners?.length){if(!t.owners.some((s)=>n.meta.owners?.includes(s)))return!1}if(t.stability?.length){if(!t.stability.includes(n.meta.stability??"stable"))return!1}if(t.domain){if(GroupingStrategies.byDomain(n)!==t.domain)return!1}if(t.keyPattern){const r=n.meta.key??n.meta.key??"",s=t.keyPattern.replace(/\*/g,".*").replace(/\?/g,".");if(!new RegExp(`^${s}$`,"i").test(r))return!1}return!0})}export function groupBy(e,t){const n=new Map;for(const r of e){const s=t(r),i=n.get(s);if(i)i.push(r);else n.set(s,[r])}return n}export function groupByToArray(e,t){const n=groupBy(e,t);return Array.from(n.entries()).map(([r,s])=>({key:r,items:s}))}export function groupByMultiple(e,t){const n=new Map;for(const r of e){const s=t(r);for(const i of s){const o=n.get(i);if(o)o.push(r);else n.set(i,[r])}}return n}export function getUniqueTags(e){const t=new Set;for(const n of e)for(const r of n.meta.tags??[])t.add(r);return Array.from(t).sort()}export function getUniqueOwners(e){const t=new Set;for(const n of e)for(const r of n.meta.owners??[])t.add(r);return Array.from(t).sort()}export function getUniqueDomains(e){const t=new Set;for(const n of e)t.add(GroupingStrategies.byDomain(n));return Array.from(t).sort()}

package/dist/registry.d.ts

@@ -0,0 +1,27 @@
+import type { OwnerShipMeta } from './ownership.js';
+import type { ContractSpecType } from './types.js';
+export interface AnySpecContract {
+    meta: OwnerShipMeta;
+}
+export declare const keyOfSpecContract: (spec: AnySpecContract) => string;
+/** In-memory registry for PresentationSpec. */
+export declare abstract class SpecContractRegistry<ContractType extends ContractSpecType, SpecContract extends AnySpecContract> {
+    protected readonly contractType: ContractType;
+    protected items: Map<string, SpecContract>;
+    protected constructor(contractType: ContractType, items?: SpecContract[]);
+    register(p: SpecContract): this;
+    count(): number;
+    list(): SpecContract[];
+    get(key: string, version?: string): SpecContract | undefined;
+    has(key: string, version?: string): boolean;
+    /** Filter presentations by criteria. */
+    filter(criteria: import('./registry-utils').RegistryFilter): SpecContract[];
+    /** List presentations with specific tag. */
+    listByTag(tag: string): SpecContract[];
+    /** List presentations by owner. */
+    listByOwner(owner: string): SpecContract[];
+    /** Group presentations by key function. */
+    groupBy(keyFn: import('./registry-utils').GroupKeyFn<SpecContract>): Map<string, SpecContract[]>;
+    /** Get unique tags from all presentations. */
+    getUniqueTags(): string[];
+}

package/dist/registry.js

@@ -0,0 +1 @@
+export class SpecContractRegistry{contractType;items=new Map;constructor(t,e){this.contractType=t;if(e)e.forEach((r)=>this.register(r))}register(t){const e=keyOfSpecContract(t);if(this.items.has(e))throw Error(`Duplicate contract \`${this.contractType}\` ${e}`);this.items.set(e,t);return this}count(){return this.items.size}list(){return[...this.items.values()]}get(t,e){if(e!=null)return this.items.get(`${t}.v${e}`);let r;for(const[n,i]of this.items.entries()){if(!n.startsWith(`${t}.v`))continue;if(!r||s(i.meta.version,r.meta.version)>0)r=i}return r}has(t,e){return!!this.get(t,e)}filter(t){return c(this.list(),t)}listByTag(t){return this.list().filter((e)=>e.meta.tags?.includes(t))}listByOwner(t){return this.list().filter((e)=>e.meta.owners?.includes(t))}groupBy(t){return a(this.list(),t)}getUniqueTags(){return o(this.list())}}import{compareVersions as s}from"compare-versions";import{filterBy as c,getUniqueTags as o,groupBy as a}from"./registry-utils.js";export const keyOfSpecContract=(t)=>`${t.meta.key}.v${t.meta.version}`;

package/dist/release/index.d.ts

@@ -0,0 +1 @@
+export * from '../versioning/index.js';

package/dist/release/index.js

@@ -0,0 +1 @@
+export*from"../versioning/index.js";

package/dist/resources.d.ts

@@ -0,0 +1,60 @@
+import * as z from 'zod';
+import type { Tag } from './ownership.js';
+export interface ResourceMeta {
+    /** URI scheme, e.g. "content://doc/{id}" or "marketplace://offers/{city}/{tag}" */
+    uriTemplate: string;
+    /** Human title for discovery */
+    title: string;
+    /** Short description */
+    description?: string;
+    /** MIME type for resource body */
+    mimeType: string;
+    /** Tags for filtering/grouping */
+    tags?: Tag[];
+}
+export interface ResourceTemplateSpec<I extends z.ZodType> {
+    meta: ResourceMeta;
+    /** Arguments to materialize the URI (zod validates input) */
+    input: I;
+    /**
+     * Resolve returns the resource body and a resolved URI.
+     * It MUST be read-only (no side effects).
+     */
+    resolve: (args: z.infer<I>, ctx: {
+        userId?: string | null;
+        orgId?: string | null;
+        locale?: string;
+    }) => Promise<{
+        uri: string;
+        mimeType?: string;
+        data: Uint8Array | string;
+    }>;
+}
+export declare function defineResourceTemplate<I extends z.ZodType>(spec: ResourceTemplateSpec<I>): ResourceTemplateSpec<I>;
+export declare class ResourceRegistry {
+    private templates;
+    register<I extends z.ZodType>(tmpl: ResourceTemplateSpec<I>): this;
+    listTemplates(): ResourceTemplateSpec<any>[];
+    /** Try to match a concrete URI to a template by naive pattern substitution */
+    match(uri: string): {
+        tmpl: ResourceTemplateSpec<any>;
+        params: Record<string, string>;
+    } | undefined;
+}
+export interface ResourceRefDescriptor<Many extends boolean> {
+    kind: 'resource_ref';
+    /** URI template, e.g. 'strit://spot/{id}' */
+    uriTemplate: string;
+    /** Variable name inside result payload to substitute into template; defaults to 'id' */
+    varName?: string;
+    /** Optional GraphQL type name to use when exposing over GraphQL (e.g., 'Spot') */
+    graphQLType: string;
+    /** Cardinality: when present and true, the handler returns an array of resources */
+    many: Many;
+}
+export declare function resourceRef<Many extends boolean>(uriTemplate: string, opts: {
+    varName?: string;
+    graphQLType: string;
+    many: Many;
+}): ResourceRefDescriptor<Many>;
+export declare function isResourceRef(x: unknown): x is ResourceRefDescriptor<boolean>;

package/dist/resources.js

@@ -0,0 +1 @@
+export class ResourceRegistry{templates=[];register(e){this.templates.push(e);return this}listTemplates(){return[...this.templates]}match(e){for(const r of this.templates){const{regex:i,names:t}=u(r.meta.uriTemplate),n=e.match(i);if(!n)continue;const s={};t.forEach((a,c)=>{const o=n[c+1];if(a&&o)s[a]=decodeURIComponent(o)});return{tmpl:r,params:s}}return}}export function defineResourceTemplate(e){return e}function p(e){return e.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")}function u(e){const r=[],i=e.split(/(\{[^}]+\})/g).filter(Boolean).map((t)=>{const n=t.match(/^\{([^}]+)\}$/);if(!n)return p(t);const[s]=n.slice(1);if(!s)return p(t);r.push(s);return"([^/]+)"}).join("");return{regex:new RegExp(`^${i}$`),names:r}}export function resourceRef(e,r){return{kind:"resource_ref",uriTemplate:e,varName:r.varName??"id",graphQLType:r.graphQLType,many:r.many}}export function isResourceRef(e){const r=e;return!!r&&r.kind==="resource_ref"&&typeof r.uriTemplate==="string"}

package/dist/results/builders.d.ts

@@ -0,0 +1,51 @@
+import type { ContractFailureSpec, ContractSuccessSpec } from './types.js';
+export declare const success: {
+    ok: <_TData = unknown>(options?: Partial<ContractSuccessSpec>) => {
+        status: number;
+        state: import("./types").ContractResultState;
+        description: string;
+        headers: Record<string, string> | undefined;
+    };
+    created: <_TData = unknown>(options?: Partial<ContractSuccessSpec>) => {
+        status: number;
+        state: import("./types").ContractResultState;
+        description: string;
+        headers: Record<string, string> | undefined;
+    };
+    accepted: <_TData = unknown>(options?: Partial<ContractSuccessSpec>) => {
+        status: number;
+        state: import("./types").ContractResultState;
+        description: string;
+        headers: Record<string, string> | undefined;
+    };
+    queued: <_TData = unknown>(options?: Partial<ContractSuccessSpec>) => {
+        status: number;
+        state: import("./types").ContractResultState;
+        description: string;
+        headers: Record<string, string> | undefined;
+    };
+    noContent: (options?: Partial<ContractSuccessSpec>) => {
+        status: number;
+        state: import("./types").ContractResultState;
+        description: string;
+        headers: Record<string, string> | undefined;
+    };
+    partial: <_TData = unknown>(options?: Partial<ContractSuccessSpec>) => {
+        status: number;
+        state: import("./types").ContractResultState;
+        description: string;
+        headers: Record<string, string> | undefined;
+    };
+};
+export declare const failure: {
+    badRequest: <TArgs extends Record<string, unknown> = Record<string, unknown>>(options?: Partial<ContractFailureSpec<TArgs>>) => ContractFailureSpec<TArgs>;
+    unauthenticated: <TArgs extends Record<string, unknown> = Record<string, unknown>>(options?: Partial<ContractFailureSpec<TArgs>>) => ContractFailureSpec<TArgs>;
+    paymentRequired: <TArgs extends Record<string, unknown> = Record<string, unknown>>(options?: Partial<ContractFailureSpec<TArgs>>) => ContractFailureSpec<TArgs>;
+    forbidden: <TArgs extends Record<string, unknown> = Record<string, unknown>>(options?: Partial<ContractFailureSpec<TArgs>>) => ContractFailureSpec<TArgs>;
+    notFound: <TArgs extends Record<string, unknown> = Record<string, unknown>>(options?: Partial<ContractFailureSpec<TArgs>>) => ContractFailureSpec<TArgs>;
+    conflict: <TArgs extends Record<string, unknown> = Record<string, unknown>>(options?: Partial<ContractFailureSpec<TArgs>>) => ContractFailureSpec<TArgs>;
+    validation: <TArgs extends Record<string, unknown> = Record<string, unknown>>(options?: Partial<ContractFailureSpec<TArgs>>) => ContractFailureSpec<TArgs>;
+    rateLimited: <TArgs extends Record<string, unknown> = Record<string, unknown>>(options?: Partial<ContractFailureSpec<TArgs>>) => ContractFailureSpec<TArgs>;
+    internal: <TArgs extends Record<string, unknown> = Record<string, unknown>>(options?: Partial<ContractFailureSpec<TArgs>>) => ContractFailureSpec<TArgs>;
+    timeout: <TArgs extends Record<string, unknown> = Record<string, unknown>>(options?: Partial<ContractFailureSpec<TArgs>>) => ContractFailureSpec<TArgs>;
+};

package/dist/results/builders.js

@@ -0,0 +1 @@
+import{isStandardRetryableStatus as s}from"./status.js";export const success={ok:(e={})=>({status:e.status??200,state:e.state??"completed",description:e.description??"The operation completed successfully.",headers:e.headers}),created:(e={})=>({status:e.status??201,state:e.state??"created",description:e.description??"The resource was created.",headers:e.headers}),accepted:(e={})=>({status:e.status??202,state:e.state??"accepted",description:e.description??"The operation was accepted.",headers:e.headers}),queued:(e={})=>({status:e.status??202,state:e.state??"queued",description:e.description??"The operation was queued.",headers:e.headers}),noContent:(e={})=>({status:e.status??204,state:e.state??"empty",description:e.description??"The operation completed without a body.",headers:e.headers}),partial:(e={})=>({status:e.status??206,state:e.state??"partial",description:e.description??"The operation partially completed.",headers:e.headers})};export const failure={badRequest:(e={})=>r(400,"validation","The request is malformed.",e),unauthenticated:(e={})=>r(401,"auth","Authentication is required.",e),paymentRequired:(e={})=>r(402,"payment","Payment or billing action is required.",e),forbidden:(e={})=>r(403,"auth","The caller is not allowed to perform this action.",e),notFound:(e={})=>r(404,"not_found","The requested resource was not found.",e),conflict:(e={})=>r(409,"conflict","The request conflicts with current state.",e),validation:(e={})=>r(422,"validation","The request did not pass validation.",e),rateLimited:(e={})=>r(429,"rate_limit","The caller has been rate limited.",{retryable:!0,...e}),internal:(e={})=>r(500,"internal","An unexpected error occurred.",{severity:"error",...e}),timeout:(e={})=>r(504,"timeout","The operation timed out.",{retryable:!0,...e})};function r(e,a,n,t){return{status:t.status??t.http??e,http:t.http,category:t.category??a,description:t.description??n,title:t.title,type:t.type,severity:t.severity??(e>=500?"error":"warning"),retryable:t.retryable??s(e),retryAfter:t.retryAfter,gqlCode:t.gqlCode,when:t.when,args:t.args}}

package/dist/results/error.d.ts

@@ -0,0 +1,8 @@
+import type { ContractProblem, StandardFailureCode } from './types.js';
+export declare class ContractSpecError<TCode extends string = StandardFailureCode, TArgs extends Record<string, unknown> = Record<string, unknown>> extends Error {
+    readonly problem: ContractProblem<TCode, TArgs>;
+    readonly code: TCode;
+    readonly status: number;
+    readonly retryable: boolean;
+    constructor(problem: ContractProblem<TCode, TArgs>);
+}

package/dist/results/error.js

@@ -0,0 +1 @@
+export class ContractSpecError extends Error{problem;code;status;retryable;constructor(t){super(t.detail??t.title);this.name="ContractSpecError";this.problem=t;this.code=t.code;this.status=t.status;this.retryable=t.retryable;Object.setPrototypeOf(this,new.target.prototype)}}

package/dist/results/factories.d.ts

@@ -0,0 +1,23 @@
+import { ContractSpecError } from './error.js';
+import type { ContractFailure, ContractFailureOptions, ContractFailureSpec, ContractProblem, ContractProblemIssue, ContractSuccess, ContractSuccessOptions, ContractSuccessSpec, ResultCatalog, StandardFailureCode } from './types.js';
+export declare function defineResultCatalog<TSuccess extends Record<string, ContractSuccessSpec>, TFailure extends Record<string, ContractFailureSpec>>(catalog: ResultCatalog<TSuccess, TFailure>): ResultCatalog<TSuccess, TFailure>;
+export declare function contractOk<TData, TCode extends string = 'OK'>(data: TData, options?: ContractSuccessOptions<TCode>): ContractSuccess<TData, TCode>;
+export declare function contractCreated<TData, TCode extends string = 'CREATED'>(data: TData, options?: Omit<ContractSuccessOptions<TCode>, 'state' | 'status'> & {
+    status?: number;
+}): ContractSuccess<TData, TCode>;
+export declare function contractAccepted<TData, TCode extends string = 'ACCEPTED'>(data: TData, options?: Omit<ContractSuccessOptions<TCode>, 'state' | 'status'> & {
+    status?: number;
+}): ContractSuccess<TData, TCode>;
+export declare function contractQueued<TData, TCode extends string = 'QUEUED'>(data: TData, options?: Omit<ContractSuccessOptions<TCode>, 'state' | 'status'> & {
+    status?: number;
+}): ContractSuccess<TData, TCode>;
+export declare function contractNoContent<TCode extends string = 'NO_CONTENT'>(options?: Omit<ContractSuccessOptions<TCode>, 'state' | 'status'> & {
+    status?: number;
+}): ContractSuccess<undefined, TCode>;
+export declare function contractPartial<TData, TCode extends string = 'PARTIAL'>(data: TData, options?: Omit<ContractSuccessOptions<TCode>, 'state' | 'status'> & {
+    status?: number;
+    partialProblems?: ContractProblem[];
+}): ContractSuccess<TData, TCode>;
+export declare function contractFail<TCode extends string = StandardFailureCode, TArgs extends Record<string, unknown> = Record<string, unknown>>(code: TCode, args?: TArgs, options?: Omit<ContractFailureOptions<TCode, TArgs>, 'code' | 'args'>): ContractFailure<TCode, TArgs>;
+export declare function contractValidationFail(issues: ContractProblemIssue[], options?: Omit<ContractFailureOptions<'VALIDATION_FAILED', Record<string, unknown>>, 'code' | 'issues'>): ContractFailure<'VALIDATION_FAILED'>;
+export declare function createContractError<TCode extends string = StandardFailureCode, TArgs extends Record<string, unknown> = Record<string, unknown>>(code: TCode, args?: TArgs, options?: Omit<ContractFailureOptions<TCode, TArgs>, 'code' | 'args'>): ContractSpecError<TCode, TArgs>;

package/dist/results/factories.js

@@ -0,0 +1 @@
+import{ContractSpecError as s}from"./error.js";import{createProblem as c}from"./problem.js";export function defineResultCatalog(e){return e}export function contractOk(e,t={}){return{ok:!0,code:t.code??"OK",status:t.status??200,data:e,state:t.state??"completed",message:t.message,warnings:t.warnings,partialProblems:t.partialProblems,traceId:t.traceId,headers:t.headers,links:t.links,pagination:t.pagination,cache:t.cache,idempotency:t.idempotency,consistency:t.consistency,versionToken:t.versionToken,source:t.source,metadata:t.metadata}}export function contractCreated(e,t={}){return contractOk(e,{...t,code:t.code??"CREATED",status:t.status??201,state:"created"})}export function contractAccepted(e,t={}){return contractOk(e,{...t,code:t.code??"ACCEPTED",status:t.status??202,state:"accepted"})}export function contractQueued(e,t={}){return contractOk(e,{...t,code:t.code??"QUEUED",status:t.status??202,state:"queued"})}export function contractNoContent(e={}){return contractOk(void 0,{...e,code:e.code??"NO_CONTENT",status:e.status??204,state:"empty"})}export function contractPartial(e,t={}){return contractOk(e,{...t,code:t.code??"PARTIAL",status:t.status??206,state:"partial"})}export function contractFail(e,t,a={}){const r=c(e,{...a,code:e,args:t});return{ok:!1,code:e,status:r.status,problem:r}}export function contractValidationFail(e,t={}){return contractFail("VALIDATION_FAILED",void 0,{...t,status:t.status??422,category:t.category??"validation",issues:e})}export function createContractError(e,t,a={}){return new s(contractFail(e,t,a).problem)}

package/dist/results/guards.d.ts

@@ -0,0 +1,7 @@
+import { ContractSpecError } from './error.js';
+import type { ContractFailure, ContractProblem, ContractResult, ContractSuccess } from './types.js';
+export declare function isContractProblem(value: unknown): value is ContractProblem;
+export declare function isContractSuccess(value: unknown): value is ContractSuccess;
+export declare function isContractFailure(value: unknown): value is ContractFailure;
+export declare function isContractResult(value: unknown): value is ContractResult;
+export declare function isContractSpecError(value: unknown): value is ContractSpecError;

package/dist/results/guards.js

@@ -0,0 +1 @@
+import{ContractSpecError as o}from"./error.js";import{isRecord as r}from"./value-utils.js";export function isContractProblem(t){return r(t)&&typeof t.type==="string"&&typeof t.title==="string"&&typeof t.status==="number"&&typeof t.code==="string"&&typeof t.category==="string"&&typeof t.retryable==="boolean"}export function isContractSuccess(t){return r(t)&&t.ok===!0&&"data"in t}export function isContractFailure(t){return r(t)&&t.ok===!1&&typeof t.code==="string"&&isContractProblem(t.problem)}export function isContractResult(t){return isContractSuccess(t)||isContractFailure(t)}export function isContractSpecError(t){return t instanceof o}

package/dist/results/index.d.js

@@ -0,0 +1 @@
+export{failure,success}from"./builders.js";export{ContractSpecError}from"./error.js";export{contractAccepted,contractCreated,contractFail,contractNoContent,contractOk,contractPartial,contractQueued,contractValidationFail,createContractError,defineResultCatalog}from"./factories.js";export{isContractFailure,isContractProblem,isContractResult,isContractSpecError,isContractSuccess}from"./guards.js";export{normalizeContractError,normalizeContractResult,problemToSafeMessage}from"./normalize.js";export{isStandardFailureCode,isStandardSuccessCode,STANDARD_FAILURE_SPECS,STANDARD_SUCCESS_SPECS,standardErrors,standardSuccess}from"./standard-specs.js";

package/dist/results/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Canonical contract result / problem surface (RFC 7807-aligned).
+ *
+ * The implementation is split into focused submodules (types, standard specs,
+ * builders, factories, guards, normalizers, problem construction). This barrel
+ * re-exports the stable public surface unchanged; internal helpers stay
+ * private to their submodule.
+ */
+export { failure, success } from './builders.js';
+export { ContractSpecError } from './error.js';
+export { contractAccepted, contractCreated, contractFail, contractNoContent, contractOk, contractPartial, contractQueued, contractValidationFail, createContractError, defineResultCatalog, } from './factories.js';
+export { isContractFailure, isContractProblem, isContractResult, isContractSpecError, isContractSuccess, } from './guards.js';
+export { normalizeContractError, normalizeContractResult, problemToSafeMessage, } from './normalize.js';
+export { isStandardFailureCode, isStandardSuccessCode, STANDARD_FAILURE_SPECS, STANDARD_SUCCESS_SPECS, standardErrors, standardSuccess, } from './standard-specs.js';
+export type { ContractFailure, ContractFailureOptions, ContractFailureSpec, ContractProblem, ContractProblemCategory, ContractProblemIssue, ContractProblemOperation, ContractProblemSeverity, ContractProblemSource, ContractResult, ContractResultCache, ContractResultIdempotency, ContractResultState, ContractSuccess, ContractSuccessOptions, ContractSuccessSpec, ResultCatalog, ResultContext, StandardFailureCode, StandardSuccessCode, } from './types.js';

package/dist/results/index.js

@@ -0,0 +1 @@
+export{failure,success}from"./builders.js";export{ContractSpecError}from"./error.js";export{contractAccepted,contractCreated,contractFail,contractNoContent,contractOk,contractPartial,contractQueued,contractValidationFail,createContractError,defineResultCatalog}from"./factories.js";export{isContractFailure,isContractProblem,isContractResult,isContractSpecError,isContractSuccess}from"./guards.js";export{normalizeContractError,normalizeContractResult,problemToSafeMessage}from"./normalize.js";export{isStandardFailureCode,isStandardSuccessCode,STANDARD_FAILURE_SPECS,STANDARD_SUCCESS_SPECS,standardErrors,standardSuccess}from"./standard-specs.js";

package/dist/results/normalize.d.ts

@@ -0,0 +1,9 @@
+import type { ContractFailure, ContractFailureSpec, ContractProblem, ContractProblemCategory, ContractResult, ContractSuccessOptions, ResultContext, StandardFailureCode, StandardSuccessCode } from './types.js';
+export declare function normalizeContractResult<TData>(value: TData | ContractResult<TData>, options?: ContractSuccessOptions<StandardSuccessCode>): ContractResult<TData>;
+export declare function normalizeContractError(error: unknown, options?: ResultContext & {
+    defaultCode?: StandardFailureCode;
+    status?: number;
+    category?: ContractProblemCategory;
+    declaredErrors?: Record<string, ContractFailureSpec>;
+}): ContractFailure<string, Record<string, unknown>>;
+export declare function problemToSafeMessage(problem: ContractProblem<string, Record<string, unknown>>): string;

package/dist/results/normalize.js

@@ -0,0 +1 @@
+import{contractFail as g,contractOk as f}from"./factories.js";import{isContractFailure as R,isContractProblem as y,isContractResult as m,isContractSpecError as S}from"./guards.js";import{createProblem as T}from"./problem.js";import{isStandardFailureCode as u}from"./standard-specs.js";import{categoryForStatus as i,isStandardRetryableStatus as P}from"./status.js";import{readIssues as I,readStringProperty as E}from"./value-utils.js";export function normalizeContractResult(t,e={}){if(m(t))return t;return f(t,e)}export function normalizeContractError(t,e={}){if(R(t)){const n=c(t.problem,e);return{...t,code:n.code,status:n.status,problem:n}}if(S(t)){const n=c(t.problem,e);return{ok:!1,code:n.code,status:n.status,problem:n}}if(y(t)){const n=c(t,e);return{ok:!1,code:n.code,status:n.status,problem:n}}const a=E(t,"code"),r=a?e.declaredErrors?.[a]:void 0,o=I(t),s=a??e.defaultCode??(o?"VALIDATION_FAILED":"INTERNAL_ERROR"),C=r||u(s)?s:"INTERNAL_ERROR",l=t instanceof Error?t.message:typeof t==="string"?t:void 0;return g(C,void 0,{status:e.status??r?.status??r?.http??(o?422:void 0),title:r?.title,detail:l,type:r?.type,category:e.category??r?.category??(o?"validation":i(e.status??r?.status??r?.http??500)),severity:r?.severity,retryable:r?.retryable,retryAfter:r?.retryAfter,gqlCode:r?.gqlCode,traceId:e.traceId,operation:e.operation,source:e.source,metadata:e.metadata,issues:o})}function c(t,e){const a=e.declaredErrors?.[t.code];if(a)return d(F(t,a),e);if(u(t.code))return d(t,e);return T("INTERNAL_ERROR",{detail:`Undeclared contract failure: ${t.code}`,metadata:{...t.metadata??{},originalCode:t.code,originalStatus:t.status,originalArgs:t.args},traceId:t.traceId??e.traceId,operation:t.operation??e.operation,source:t.source??e.source})}function F(t,e){const a=e.status??e.http??t.status;return{...t,status:a,type:e.type??t.type,title:e.title??t.title,detail:t.detail??e.description,category:e.category??i(a),severity:e.severity??(a>=500?"error":"warning"),retryable:e.retryable??P(a),retryAfter:t.retryAfter??e.retryAfter,gqlCode:e.gqlCode??t.gqlCode}}function d(t,e){return{...t,traceId:t.traceId??e.traceId,operation:t.operation??e.operation,source:t.source??e.source,metadata:t.metadata??e.metadata}}export function problemToSafeMessage(t){return t.detail??t.title}

package/dist/results/problem.d.ts

@@ -0,0 +1,2 @@
+import type { ContractFailureOptions, ContractProblem } from './types.js';
+export declare function createProblem<TCode extends string, TArgs extends Record<string, unknown>>(code: TCode, options: ContractFailureOptions<TCode, TArgs>): ContractProblem<TCode, TArgs>;

package/dist/results/problem.js

@@ -0,0 +1 @@
+import{STANDARD_FAILURE_SPECS as s}from"./standard-specs.js";import{categoryForStatus as o,isStandardRetryableStatus as i}from"./status.js";export function createProblem(r,e){const a=e.status??l(r),t=s[r],n=e.category??t?.category??o(a),c=e.title??t?.title??u(r);return{type:e.type??t?.type??`https://contractspec.io/problems/${r.toLowerCase().replace(/_/g,"-")}`,title:c,status:a,code:r,detail:e.detail,instance:e.instance,category:n,severity:e.severity??t?.severity??(a>=500?"error":"warning"),retryable:e.retryable??t?.retryable??i(a),retryAfter:e.retryAfter??t?.retryAfter,gqlCode:e.gqlCode??t?.gqlCode,traceId:e.traceId,operation:e.operation,source:e.source,args:e.args,issues:e.issues,metadata:e.metadata,versionToken:e.versionToken}}function l(r){return s[r]?.status??500}function u(r){return r.toLowerCase().split("_").map((e)=>e.charAt(0).toUpperCase()+e.slice(1)).join(" ")}

package/dist/results/result-specs.d.ts

@@ -0,0 +1,73 @@
+import type { QueryConsistency, VersionToken } from '../query/index.js';
+import type { ContractProblem, ContractProblemCategory, ContractProblemIssue, ContractProblemOperation, ContractProblemSeverity, ContractProblemSource, ContractResultCache, ContractResultIdempotency, ContractResultState } from './types.js';
+export interface ContractSuccessSpec {
+    status: number;
+    state?: ContractResultState;
+    description?: string;
+    headers?: Record<string, string>;
+}
+export interface ContractFailureSpec<TArgs extends Record<string, unknown> = Record<string, unknown>> {
+    status?: number;
+    /** Preferred human-readable failure description. Legacy specs may use `message`. */
+    description?: string;
+    /** Compatibility alias used by older operation specs. */
+    message?: string;
+    /** Compatibility alias used by older operation specs. */
+    code?: string;
+    /** Compatibility alias for retryable used by older operation specs. */
+    recoverable?: boolean;
+    title?: string;
+    type?: string;
+    category?: ContractProblemCategory;
+    severity?: ContractProblemSeverity;
+    retryable?: boolean;
+    retryAfter?: number;
+    gqlCode?: string;
+    http?: number;
+    when?: string;
+    args?: TArgs;
+}
+export interface ResultCatalog<TSuccess extends Record<string, ContractSuccessSpec> = Record<string, ContractSuccessSpec>, TFailure extends Record<string, ContractFailureSpec> = Record<string, ContractFailureSpec>> {
+    success?: TSuccess;
+    errors?: TFailure;
+}
+export interface ResultContext {
+    traceId?: string;
+    operation?: ContractProblemOperation;
+    source?: ContractProblemSource;
+    metadata?: Record<string, unknown>;
+}
+export interface ContractSuccessOptions<TCode extends string> {
+    code?: TCode;
+    status?: number;
+    state?: ContractResultState;
+    message?: string;
+    warnings?: ContractProblem[];
+    partialProblems?: ContractProblem[];
+    traceId?: string;
+    headers?: Record<string, string>;
+    links?: Record<string, string>;
+    pagination?: Record<string, unknown>;
+    cache?: ContractResultCache;
+    idempotency?: ContractResultIdempotency;
+    consistency?: QueryConsistency;
+    versionToken?: VersionToken;
+    source?: ContractProblemSource;
+    metadata?: Record<string, unknown>;
+}
+export interface ContractFailureOptions<TCode extends string, TArgs extends Record<string, unknown>> extends ResultContext {
+    code?: TCode;
+    status?: number;
+    title?: string;
+    detail?: string;
+    type?: string;
+    category?: ContractProblemCategory;
+    severity?: ContractProblemSeverity;
+    retryable?: boolean;
+    retryAfter?: number | Date;
+    gqlCode?: string;
+    instance?: string;
+    args?: TArgs;
+    issues?: ContractProblemIssue[];
+    versionToken?: VersionToken;
+}

package/dist/results/standard-specs.d.ts

@@ -0,0 +1,90 @@
+import type { ContractFailureSpec, ContractSuccessSpec, StandardFailureCode, StandardSuccessCode } from './types.js';
+export declare const STANDARD_SUCCESS_SPECS: {
+    readonly OK: ContractSuccessSpec;
+    readonly CREATED: ContractSuccessSpec;
+    readonly ACCEPTED: ContractSuccessSpec;
+    readonly NO_CONTENT: ContractSuccessSpec;
+    readonly PARTIAL: ContractSuccessSpec;
+    readonly MULTI_STATUS: ContractSuccessSpec;
+    readonly QUEUED: ContractSuccessSpec;
+};
+export declare const STANDARD_FAILURE_SPECS: {
+    readonly APPROVAL_REQUIRED: ContractFailureSpec<Record<string, unknown>>;
+    readonly CEREMONY_REQUIRED: ContractFailureSpec<Record<string, unknown>>;
+    readonly BAD_REQUEST: ContractFailureSpec<Record<string, unknown>>;
+    readonly UNAUTHENTICATED: ContractFailureSpec<Record<string, unknown>>;
+    readonly PAYMENT_REQUIRED: ContractFailureSpec<Record<string, unknown>>;
+    readonly FORBIDDEN: ContractFailureSpec<Record<string, unknown>>;
+    readonly NOT_FOUND: ContractFailureSpec<Record<string, unknown>>;
+    readonly METHOD_NOT_ALLOWED: ContractFailureSpec<Record<string, unknown>>;
+    readonly CONFLICT: ContractFailureSpec<Record<string, unknown>>;
+    readonly GONE: ContractFailureSpec<Record<string, unknown>>;
+    readonly PRECONDITION_FAILED: ContractFailureSpec<Record<string, unknown>>;
+    readonly VALIDATION_FAILED: ContractFailureSpec<Record<string, unknown>>;
+    readonly RATE_LIMITED: ContractFailureSpec<Record<string, unknown>>;
+    readonly INTERNAL_ERROR: ContractFailureSpec<Record<string, unknown>>;
+    readonly NOT_IMPLEMENTED: ContractFailureSpec<Record<string, unknown>>;
+    readonly BAD_GATEWAY: ContractFailureSpec<Record<string, unknown>>;
+    readonly SERVICE_UNAVAILABLE: ContractFailureSpec<Record<string, unknown>>;
+    readonly TIMEOUT: ContractFailureSpec<Record<string, unknown>>;
+};
+export declare const standardSuccess: {
+    OK: ContractSuccessSpec;
+    CREATED: ContractSuccessSpec;
+    ACCEPTED: ContractSuccessSpec;
+    NO_CONTENT: ContractSuccessSpec;
+    PARTIAL: ContractSuccessSpec;
+    MULTI_STATUS: ContractSuccessSpec;
+    QUEUED: ContractSuccessSpec;
+    pick<const TCodes extends readonly StandardSuccessCode[]>(...codes: TCodes): Pick<{
+        readonly OK: ContractSuccessSpec;
+        readonly CREATED: ContractSuccessSpec;
+        readonly ACCEPTED: ContractSuccessSpec;
+        readonly NO_CONTENT: ContractSuccessSpec;
+        readonly PARTIAL: ContractSuccessSpec;
+        readonly MULTI_STATUS: ContractSuccessSpec;
+        readonly QUEUED: ContractSuccessSpec;
+    }, StandardSuccessCode>;
+};
+export declare const standardErrors: {
+    APPROVAL_REQUIRED: ContractFailureSpec<Record<string, unknown>>;
+    CEREMONY_REQUIRED: ContractFailureSpec<Record<string, unknown>>;
+    BAD_REQUEST: ContractFailureSpec<Record<string, unknown>>;
+    UNAUTHENTICATED: ContractFailureSpec<Record<string, unknown>>;
+    PAYMENT_REQUIRED: ContractFailureSpec<Record<string, unknown>>;
+    FORBIDDEN: ContractFailureSpec<Record<string, unknown>>;
+    NOT_FOUND: ContractFailureSpec<Record<string, unknown>>;
+    METHOD_NOT_ALLOWED: ContractFailureSpec<Record<string, unknown>>;
+    CONFLICT: ContractFailureSpec<Record<string, unknown>>;
+    GONE: ContractFailureSpec<Record<string, unknown>>;
+    PRECONDITION_FAILED: ContractFailureSpec<Record<string, unknown>>;
+    VALIDATION_FAILED: ContractFailureSpec<Record<string, unknown>>;
+    RATE_LIMITED: ContractFailureSpec<Record<string, unknown>>;
+    INTERNAL_ERROR: ContractFailureSpec<Record<string, unknown>>;
+    NOT_IMPLEMENTED: ContractFailureSpec<Record<string, unknown>>;
+    BAD_GATEWAY: ContractFailureSpec<Record<string, unknown>>;
+    SERVICE_UNAVAILABLE: ContractFailureSpec<Record<string, unknown>>;
+    TIMEOUT: ContractFailureSpec<Record<string, unknown>>;
+    pick<const TCodes extends readonly StandardFailureCode[]>(...codes: TCodes): Pick<{
+        readonly APPROVAL_REQUIRED: ContractFailureSpec<Record<string, unknown>>;
+        readonly CEREMONY_REQUIRED: ContractFailureSpec<Record<string, unknown>>;
+        readonly BAD_REQUEST: ContractFailureSpec<Record<string, unknown>>;
+        readonly UNAUTHENTICATED: ContractFailureSpec<Record<string, unknown>>;
+        readonly PAYMENT_REQUIRED: ContractFailureSpec<Record<string, unknown>>;
+        readonly FORBIDDEN: ContractFailureSpec<Record<string, unknown>>;
+        readonly NOT_FOUND: ContractFailureSpec<Record<string, unknown>>;
+        readonly METHOD_NOT_ALLOWED: ContractFailureSpec<Record<string, unknown>>;
+        readonly CONFLICT: ContractFailureSpec<Record<string, unknown>>;
+        readonly GONE: ContractFailureSpec<Record<string, unknown>>;
+        readonly PRECONDITION_FAILED: ContractFailureSpec<Record<string, unknown>>;
+        readonly VALIDATION_FAILED: ContractFailureSpec<Record<string, unknown>>;
+        readonly RATE_LIMITED: ContractFailureSpec<Record<string, unknown>>;
+        readonly INTERNAL_ERROR: ContractFailureSpec<Record<string, unknown>>;
+        readonly NOT_IMPLEMENTED: ContractFailureSpec<Record<string, unknown>>;
+        readonly BAD_GATEWAY: ContractFailureSpec<Record<string, unknown>>;
+        readonly SERVICE_UNAVAILABLE: ContractFailureSpec<Record<string, unknown>>;
+        readonly TIMEOUT: ContractFailureSpec<Record<string, unknown>>;
+    }, StandardFailureCode>;
+};
+export declare function isStandardSuccessCode(code: string): code is StandardSuccessCode;
+export declare function isStandardFailureCode(code: string): code is StandardFailureCode;

package/dist/results/standard-specs.js

@@ -0,0 +1 @@
+import{isStandardRetryableStatus as s}from"./status.js";const o=(t,n,a)=>({status:t,state:n,description:a});const e=(t,n,a,r={})=>({status:t,category:n,description:a,retryable:r.retryable??s(t),severity:r.severity??(t>=500?"error":"warning"),title:r.title,type:r.type});export const STANDARD_SUCCESS_SPECS={OK:o(200,"completed","The operation completed successfully."),CREATED:o(201,"created","The resource was created."),ACCEPTED:o(202,"accepted","The operation was accepted."),NO_CONTENT:o(204,"empty","The operation completed without a body."),PARTIAL:o(206,"partial","The operation partially completed."),MULTI_STATUS:o(207,"partial","The operation returned multiple statuses."),QUEUED:o(202,"queued","The operation was queued for asynchronous work.")};export const STANDARD_FAILURE_SPECS={APPROVAL_REQUIRED:e(403,"policy","A valid scoped approval receipt is required for this operation."),CEREMONY_REQUIRED:e(403,"auth","A valid host-bound, unexpired, single-use ceremony is required for this operation."),BAD_REQUEST:e(400,"validation","The request is malformed."),UNAUTHENTICATED:e(401,"auth","Authentication is required."),PAYMENT_REQUIRED:e(402,"payment","Payment or billing action is required."),FORBIDDEN:e(403,"auth","The caller is not allowed to perform this action."),NOT_FOUND:e(404,"not_found","The requested resource was not found."),METHOD_NOT_ALLOWED:e(405,"validation","The requested method is not allowed."),CONFLICT:e(409,"conflict","The request conflicts with current state."),GONE:e(410,"not_found","The requested resource is no longer available."),PRECONDITION_FAILED:e(412,"conflict","A required precondition failed."),VALIDATION_FAILED:e(422,"validation","The request did not pass validation."),RATE_LIMITED:e(429,"rate_limit","The caller has been rate limited.",{retryable:!0}),INTERNAL_ERROR:e(500,"internal","An unexpected error occurred.",{severity:"error"}),NOT_IMPLEMENTED:e(501,"internal","This operation is not implemented.",{severity:"error"}),BAD_GATEWAY:e(502,"dependency","An upstream dependency failed.",{retryable:!0}),SERVICE_UNAVAILABLE:e(503,"dependency","The service is unavailable.",{retryable:!0}),TIMEOUT:e(504,"timeout","The operation timed out.",{retryable:!0})};function i(t,n){const a={};for(const r of n)a[r]=t[r];return a}export const standardSuccess={...STANDARD_SUCCESS_SPECS,pick(...t){return i(STANDARD_SUCCESS_SPECS,t)}};export const standardErrors={...STANDARD_FAILURE_SPECS,pick(...t){return i(STANDARD_FAILURE_SPECS,t)}};const c=new Set(Object.keys(STANDARD_SUCCESS_SPECS));const d=new Set(Object.keys(STANDARD_FAILURE_SPECS));export function isStandardSuccessCode(t){return c.has(t)}export function isStandardFailureCode(t){return d.has(t)}

package/dist/results/status.d.ts

@@ -0,0 +1,3 @@
+import type { ContractProblemCategory } from './types.js';
+export declare function categoryForStatus(status: number): ContractProblemCategory;
+export declare function isStandardRetryableStatus(status: number): boolean;

package/dist/results/status.js

@@ -0,0 +1 @@
+export function categoryForStatus(r){if(r===401)return"auth";if(r===402)return"payment";if(r===403)return"auth";if(r===404||r===410)return"not_found";if(r===409||r===412)return"conflict";if(r===429)return"rate_limit";if(r===504)return"timeout";if(r>=400&&r<500)return"validation";if(r>=500)return"internal";return"internal"}export function isStandardRetryableStatus(r){return r===429||r===502||r===503||r===504}