@nomosprotocol/sdk 1.0.0 → 1.1.0

package/dist/index.d.cts

@@ -0,0 +1,360 @@
+interface VerifyDecisionParams {
+    /** Artifact ID from NOMOS Studio or the Exchange */
+    artifact_id: string;
+    /** The data fields this decision is based on */
+    decision_context: Record<string, unknown>;
+    /** Optional: the AI's proposed decision (for audit trail) */
+    proposed_decision?: string;
+    /** Optional: unique ID for idempotency */
+    correlation_id?: string;
+}
+interface ListArtifactsParams {
+    /** Filter by autonomy band */
+    band?: 'autonomous' | 'bounded' | 'human_governed';
+    /** Filter by domain */
+    domain?: string;
+    /** Filter by jurisdiction tag */
+    jurisdiction?: string;
+    /** Sort order */
+    sort?: 'newest' | 'top_rated' | 'most_used';
+    /** Number of results (default 20, max 100) */
+    limit?: number;
+    /** Pagination offset */
+    offset?: number;
+}
+interface GenerateGovernanceParams {
+    /** Policy documents as plain text */
+    policies: string[];
+    /** Historical decision logs (CSV rows or JSON objects) */
+    decision_logs?: Record<string, unknown>[];
+    /** Domain name (e.g. "loan_approval") */
+    domain?: string;
+    /** Organisation name */
+    organisation?: string;
+}
+interface DetectContradictionsParams {
+    /** Array of rules to check */
+    rules: Array<{
+        id: string;
+        condition: string;
+        outcome: string;
+        priority?: number;
+    }>;
+}
+type Verdict = 'auto_approved' | 'auto_rejected' | 'escalated' | 'pending_human_review';
+interface VerifyDecisionResult {
+    /** Whether the decision is permitted under current governance */
+    allowed: boolean;
+    /** Machine-readable verdict */
+    verdict: Verdict;
+    /** Human-readable explanation */
+    verdict_description: string;
+    /** The rule that triggered this verdict (if any) */
+    rule_reference?: string;
+    /** SHA-256 hash of the audit record — store this for compliance */
+    audit_record?: string;
+    /** Artifact that governed this decision */
+    artifact_id: string;
+    /** Execution ID for tracing */
+    execution_id?: string;
+    /** ISO timestamp */
+    decided_at: string;
+}
+interface Artifact {
+    id: string;
+    title: string;
+    description?: string;
+    domain?: string;
+    verification_tier: 'DECLARED' | 'VALIDATED' | 'CERTIFIED' | 'PROVEN' | 'SOVEREIGN';
+    autonomy_band: 'autonomous' | 'bounded' | 'human_governed';
+    ari_score?: number;
+    rule_count?: number;
+    jurisdiction_tags: string[];
+    industry_tags: string[];
+    publisher_org?: string;
+    seal_hash?: string;
+    downloads: number;
+    rating?: number;
+    price_usd: number;
+    published_at?: string;
+    created_at: string;
+}
+interface ArtifactList {
+    data: Artifact[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+interface Contradiction {
+    type: 'threshold_conflict' | 'role_conflict' | 'ghost_term' | 'rule_collision' | 'layer_divergence';
+    severity: 'critical' | 'warning' | 'info';
+    rule_ids: string[];
+    description: string;
+    suggested_resolution?: string;
+}
+interface DetectContradictionsResult {
+    contradiction_count: number;
+    contradictions: Contradiction[];
+    clean: boolean;
+}
+interface GenerateGovernanceResult {
+    artifact_id: string;
+    seal_hash: string;
+    ari_score: number;
+    autonomy_band: 'autonomous' | 'bounded' | 'human_governed';
+    rule_count: number;
+    verification_tier: string;
+    download_url?: string;
+}
+interface NomosConfig {
+    /** Base URL override — defaults to https://nomos.ai */
+    baseUrl?: string;
+    /** Max retries on 429 / 5xx (default: 3) */
+    maxRetries?: number;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+}
+interface RequestOptions {
+    /** Per-request timeout override in ms */
+    timeout?: number;
+    /** Per-request max retries override */
+    maxRetries?: number;
+    /** Idempotency key — safe to retry the same request server-side */
+    idempotencyKey?: string;
+    /** Per-request API key — useful for multi-tenant platforms */
+    apiKey?: string;
+}
+interface NomosRawResponse {
+    /** x-request-id header value — include in support tickets */
+    requestId: string;
+    statusCode: number;
+    headers: Record<string, string>;
+}
+/** Every SDK response carries `.lastResponse` for debugging and tracing. */
+type WithLastResponse<T> = T & {
+    lastResponse: NomosRawResponse;
+};
+type NomosWebhookEventType = 'artifact.sealed' | 'artifact.published' | 'decision.verified' | 'decision.escalated' | 'exchange.purchased' | 'exchange.reviewed' | 'drift.detected';
+interface NomosWebhookEvent {
+    id: string;
+    type: NomosWebhookEventType;
+    created: number;
+    artifact_id?: string;
+    data: Record<string, unknown>;
+}
+
+interface HttpClientOptions {
+    apiKey: string;
+    baseUrl: string;
+    maxRetries: number;
+    timeout: number;
+}
+interface HttpResponse<T> {
+    data: T;
+    lastResponse: NomosRawResponse;
+}
+declare class HttpClient {
+    private readonly opts;
+    constructor(opts: HttpClientOptions);
+    get<T>(path: string, reqOpts?: RequestOptions): Promise<HttpResponse<T>>;
+    post<T>(path: string, body: unknown, reqOpts?: RequestOptions): Promise<HttpResponse<T>>;
+    private request;
+}
+
+declare class Decisions {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Verify whether an AI decision is permitted under a governance artifact.
+     *
+     * Public demo artifacts (`pub_*`) work without an API key.
+     * Custom artifacts require a valid API key.
+     *
+     * @example
+     * const result = await nomos.decisions.verify({
+     *   artifact_id: 'pub_lending_v1',
+     *   decision_context: { credit_score: 720, loan_amount: 50000 },
+     * });
+     *
+     * if (!result.allowed) {
+     *   throw new Error(`Blocked: ${result.verdict_description}`);
+     * }
+     *
+     * // Debugging / tracing
+     * console.log(result.lastResponse.requestId);
+     *
+     * @example
+     * // Per-request options
+     * const result = await nomos.decisions.verify(params, {
+     *   idempotencyKey: `verify-${transactionId}`,
+     *   timeout: 5000,
+     * });
+     */
+    verify(params: VerifyDecisionParams, opts?: RequestOptions): Promise<WithLastResponse<VerifyDecisionResult>>;
+}
+
+declare class Artifacts {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Retrieve a single artifact by ID.
+     *
+     * @example
+     * const artifact = await nomos.artifacts.retrieve('loan_approval_v1');
+     * console.log(artifact.ari_score, artifact.autonomy_band);
+     * console.log(artifact.lastResponse.requestId); // for support tickets
+     */
+    retrieve(artifactId: string, opts?: RequestOptions): Promise<WithLastResponse<Artifact>>;
+    /**
+     * List published artifacts on the Exchange with optional filters.
+     *
+     * @example
+     * const { data, total } = await nomos.artifacts.list({ band: 'autonomous', limit: 10 });
+     *
+     * @example
+     * // With per-request options
+     * const page = await nomos.artifacts.list({ limit: 20 }, { timeout: 5000 });
+     */
+    list(params?: ListArtifactsParams, opts?: RequestOptions): Promise<WithLastResponse<ArtifactList>>;
+    /**
+     * Auto-paginating iterator — yields every artifact across all pages.
+     * Stops automatically when the last page is reached.
+     *
+     * @example
+     * for await (const artifact of nomos.artifacts.listAutoPaging({ band: 'autonomous' })) {
+     *   console.log(artifact.title, artifact.ari_score);
+     * }
+     */
+    listAutoPaging(params?: ListArtifactsParams, opts?: RequestOptions): AsyncGenerator<Artifact>;
+}
+
+declare class Governance {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Generate a sealed .nomos governance artifact from policy documents
+     * and optional historical decision logs.
+     *
+     * @example
+     * const artifact = await nomos.governance.generate({
+     *   policies: [policyText],
+     *   decision_logs: historicalRows,
+     *   domain: 'loan_approval',
+     * });
+     * console.log(artifact.ari_score, artifact.seal_hash);
+     */
+    generate(params: GenerateGovernanceParams, opts?: RequestOptions): Promise<WithLastResponse<GenerateGovernanceResult>>;
+    /**
+     * Detect contradictions and conflicts in a rule set before sealing.
+     *
+     * @example
+     * const report = await nomos.governance.detectContradictions({ rules });
+     * if (!report.clean) {
+     *   console.log(report.contradictions);
+     * }
+     */
+    detectContradictions(params: DetectContradictionsParams, opts?: RequestOptions): Promise<WithLastResponse<DetectContradictionsResult>>;
+}
+
+declare class Webhooks {
+    /**
+     * Verify a NOMOS webhook signature and return the parsed event.
+     *
+     * Signature header format: `t=<unix_ts>,v1=<hmac_sha256_hex>`
+     * Signed payload: `<timestamp>.<raw_body>`
+     *
+     * @example
+     * // Express
+     * app.post('/webhooks/nomos', express.raw({ type: 'application/json' }), async (req, res) => {
+     *   const event = await nomos.webhooks.constructEvent(
+     *     req.body,
+     *     req.headers['nomos-signature'] as string,
+     *     process.env.NOMOS_WEBHOOK_SECRET!,
+     *   );
+     *   console.log(event.type, event.data);
+     *   res.sendStatus(200);
+     * });
+     *
+     * @throws {NomosWebhookSignatureError} if signature is invalid, expired, or malformed
+     */
+    constructEvent(payload: string | Uint8Array, signature: string, secret: string, toleranceSeconds?: number): Promise<NomosWebhookEvent>;
+    /**
+     * Verify a webhook signature without parsing the event.
+     * Returns `true` if valid, `false` if not (never throws).
+     *
+     * @example
+     * const valid = await nomos.webhooks.verifySignature(rawBody, sig, secret);
+     * if (!valid) return res.sendStatus(400);
+     */
+    verifySignature(payload: string | Uint8Array, signature: string, secret: string, toleranceSeconds?: number): Promise<boolean>;
+}
+
+type NomosErrorCode = 'authentication_error' | 'authorization_error' | 'rate_limit_error' | 'validation_error' | 'not_found' | 'api_error' | 'network_error' | 'webhook_signature_error';
+declare class NomosError extends Error {
+    readonly code: NomosErrorCode;
+    readonly status?: number;
+    readonly requestId?: string;
+    constructor(message: string, code: NomosErrorCode, status?: number, requestId?: string);
+}
+declare class NomosAuthenticationError extends NomosError {
+    constructor(message?: string, requestId?: string);
+}
+declare class NomosAuthorizationError extends NomosError {
+    constructor(message?: string, requestId?: string);
+}
+declare class NomosRateLimitError extends NomosError {
+    readonly retryAfter?: number;
+    constructor(message?: string, retryAfter?: number, requestId?: string);
+}
+declare class NomosValidationError extends NomosError {
+    readonly details?: unknown;
+    constructor(message: string, details?: unknown, requestId?: string);
+}
+declare class NomosNotFoundError extends NomosError {
+    constructor(message: string, requestId?: string);
+}
+declare class NomosAPIError extends NomosError {
+    constructor(message: string, status: number, requestId?: string);
+}
+declare class NomosNetworkError extends NomosError {
+    constructor(message: string);
+}
+declare class NomosWebhookSignatureError extends NomosError {
+    constructor(message: string);
+}
+
+type errors_NomosAPIError = NomosAPIError;
+declare const errors_NomosAPIError: typeof NomosAPIError;
+type errors_NomosAuthenticationError = NomosAuthenticationError;
+declare const errors_NomosAuthenticationError: typeof NomosAuthenticationError;
+type errors_NomosAuthorizationError = NomosAuthorizationError;
+declare const errors_NomosAuthorizationError: typeof NomosAuthorizationError;
+type errors_NomosError = NomosError;
+declare const errors_NomosError: typeof NomosError;
+type errors_NomosErrorCode = NomosErrorCode;
+type errors_NomosNetworkError = NomosNetworkError;
+declare const errors_NomosNetworkError: typeof NomosNetworkError;
+type errors_NomosNotFoundError = NomosNotFoundError;
+declare const errors_NomosNotFoundError: typeof NomosNotFoundError;
+type errors_NomosRateLimitError = NomosRateLimitError;
+declare const errors_NomosRateLimitError: typeof NomosRateLimitError;
+type errors_NomosValidationError = NomosValidationError;
+declare const errors_NomosValidationError: typeof NomosValidationError;
+type errors_NomosWebhookSignatureError = NomosWebhookSignatureError;
+declare const errors_NomosWebhookSignatureError: typeof NomosWebhookSignatureError;
+declare namespace errors {
+  export { errors_NomosAPIError as NomosAPIError, errors_NomosAuthenticationError as NomosAuthenticationError, errors_NomosAuthorizationError as NomosAuthorizationError, errors_NomosError as NomosError, type errors_NomosErrorCode as NomosErrorCode, errors_NomosNetworkError as NomosNetworkError, errors_NomosNotFoundError as NomosNotFoundError, errors_NomosRateLimitError as NomosRateLimitError, errors_NomosValidationError as NomosValidationError, errors_NomosWebhookSignatureError as NomosWebhookSignatureError };
+}
+
+declare class Nomos {
+    readonly decisions: Decisions;
+    readonly artifacts: Artifacts;
+    readonly governance: Governance;
+    readonly webhooks: Webhooks;
+    /** Whether this instance is using a live or test API key. */
+    readonly mode: 'live' | 'test';
+    static readonly errors: typeof errors;
+    constructor(apiKey: string, config?: NomosConfig);
+}
+
+export { type Artifact, type ArtifactList, type Contradiction, type DetectContradictionsParams, type DetectContradictionsResult, type GenerateGovernanceParams, type GenerateGovernanceResult, type ListArtifactsParams, Nomos, NomosAPIError, NomosAuthenticationError, NomosAuthorizationError, type NomosConfig, NomosError, type NomosErrorCode, NomosNetworkError, NomosNotFoundError, NomosRateLimitError, type NomosRawResponse, NomosValidationError, type NomosWebhookEvent, type NomosWebhookEventType, NomosWebhookSignatureError, type RequestOptions, type Verdict, type VerifyDecisionParams, type VerifyDecisionResult, type WithLastResponse };