@noresponse/node 1.0.0 → 1.0.1

package/README.md

@@ -24,7 +24,7 @@ if (assessment.status === "pending") {
 }
 ```
 
-Also provides `getAssessment(assessmentId, { responseMode })` and `queryAssessments({ account_id, limit, cursor, responseMode })`. `responseMode: "detailed"` (with the `detailed` key scope) adds `risk.details` and `signals[]`; `raw` is refused.
+Also provides `getAssessment(assessmentId, { responseMode })`, `queryAssessments({ account_id, limit, cursor, responseMode })` and `recordOutcome(assessmentId, { outcome, idempotencyKey, observedAt, externalRef, notes })`, which reports what was later learned about the account (`confirmed_abuse`, `account_takeover`, `chargeback`, `false_positive`, `legitimate` or `unknown`). `responseMode: "detailed"` (with the `detailed` key scope) adds `risk.details` and `signals[]`; `raw` is refused. Pass `flow` (`signup`, `login`, `recovery`, or `profile_change`) and an uppercase `region` when the event is not the default signup. The client retries network failures, 429 and 503 a bounded number of times while preserving the same idempotency key.
 
 Webhooks: `verifyWebhook(rawBody, headerPairs, secrets, nowSeconds?)` checks the `v1=` HMAC-SHA256 signature over the exact raw request bytes, the 300-second timestamp window and the event id, and returns the typed `WebhookEvent`. It takes **raw header pairs** so it can refuse a repeated header, including a case variant. Never parse then re-stringify the body before verifying. An `assessment.updated` event's `data` is the full assessment, exactly as `getAssessment` returns it: `webhookAssessment(event)` returns it as a typed `Assessment`. Keep the highest `assessment_version` per assessment. When receiving `endpoint.verification`, respond with `webhookVerificationResponse(event)`.
 

package/dist/auth.d.ts

@@ -0,0 +1,11 @@
+import type { AssessmentRequestAuthContext } from "./generated/models.js";
+export type VerifiedClaims = Record<string, unknown>;
+export type AuthContextOverrides = Partial<AssessmentRequestAuthContext>;
+/** Map verified WorkOS/AuthKit claims plus verified user/session-record overrides. */
+export declare function fromWorkOS(claims: VerifiedClaims, overrides?: AuthContextOverrides): AssessmentRequestAuthContext;
+/** Map verified Clerk session claims. Pass Session.createdAt as session_created_at. */
+export declare function fromClerk(claims: VerifiedClaims, overrides?: AuthContextOverrides): AssessmentRequestAuthContext;
+/** Map verified Auth0 ID-token, userinfo, or normalized session claims. Do not pass an opaque API access token. */
+export declare function fromAuth0(claims: VerifiedClaims, overrides?: AuthContextOverrides): AssessmentRequestAuthContext;
+/** Generic OIDC adapter for providers without a first-class helper. */
+export declare function fromOIDC(provider: string, claims: VerifiedClaims, overrides?: AuthContextOverrides): AssessmentRequestAuthContext;

package/dist/auth.js

@@ -0,0 +1,111 @@
+function text(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function iso(value) {
+    if (typeof value === "string")
+        return value;
+    // Whole UTC seconds (the fraction is truncated), as the Go and Python helpers write it.
+    if (typeof value === "number" && Number.isFinite(value))
+        return new Date(Math.trunc(value) * 1000).toISOString().replace(".000Z", "Z");
+    return undefined;
+}
+// Defaults are the auth-context.schema.json bounds for roles and scopes (32
+// items of at most 64 characters); audiences are 8 x 256 and amr 8 x 32. The
+// Go and Python helpers apply the same caps. Over-long values are dropped,
+// not truncated.
+function bounded(values, limit, maxLength) {
+    const kept = values
+        .filter((item) => typeof item === "string" && item.length > 0 && [...item].length <= maxLength)
+        .slice(0, limit);
+    return kept.length ? kept : undefined;
+}
+function strings(value, limit = 32, maxLength = 64) {
+    if (typeof value === "string")
+        return bounded(value.split(/\s+/), limit, maxLength);
+    return Array.isArray(value) ? bounded(value, limit, maxLength) : undefined;
+}
+function delimitedStrings(value, limit = 32, maxLength = 64) {
+    if (typeof value !== "string")
+        return strings(value, limit, maxLength);
+    return bounded(value.split(/[\s,]+/).map(item => item.trim()), limit, maxLength);
+}
+function audiences(value) {
+    return strings(value, 8, 256);
+}
+function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+function actorPresent(value) {
+    const record = object(value);
+    return Boolean(record ? text(record.sub) ?? text(record.email) : text(value));
+}
+function base(provider, claims, overrides = {}, options = {}) {
+    const issuer = text(overrides.issuer) ?? text(claims.iss);
+    const subject = text(overrides.subject) ?? text(claims.sub);
+    if (!issuer || !subject)
+        throw new Error("NoResponse auth context requires verified issuer and subject");
+    const claimAudiences = audiences(claims.aud);
+    const mergedAudiences = overrides.audiences ?? claimAudiences;
+    return {
+        provider,
+        issuer,
+        subject,
+        ...(mergedAudiences?.length ? { audiences: mergedAudiences, audience: overrides.audience ?? mergedAudiences[0] } : {}),
+        ...(options.includeIssuedAt !== false && iso(claims.iat) ? { issued_at: iso(claims.iat) } : {}),
+        ...(iso(claims.exp) ? { expires_at: iso(claims.exp) } : {}),
+        ...(iso(claims.auth_time) ? { auth_time: iso(claims.auth_time) } : {}),
+        ...(text(claims.sid) ? { session_id: text(claims.sid) } : {}),
+        ...(text(claims.jti) ? { token_id: text(claims.jti) } : {}),
+        verified: true,
+        transport: "backend",
+        ...overrides,
+    };
+}
+/** Map verified WorkOS/AuthKit claims plus verified user/session-record overrides. */
+export function fromWorkOS(claims, overrides = {}) {
+    const defaults = {
+        organization_id: text(claims.org_id),
+        roles: strings(claims.roles ?? claims.role),
+        scopes: strings(claims.permissions),
+        impersonated: actorPresent(claims.act),
+    };
+    return base("workos", claims, { ...defaults, ...overrides });
+}
+/** Map verified Clerk session claims. Pass Session.createdAt as session_created_at. */
+export function fromClerk(claims, overrides = {}) {
+    const org = object(claims.o);
+    const secondFactorAgeMinutes = Array.isArray(claims.fva) && typeof claims.fva[1] === "number" && Number.isFinite(claims.fva[1]) ? claims.fva[1] : undefined;
+    const mfa = secondFactorAgeMinutes !== undefined && secondFactorAgeMinutes >= 0
+        ? { present: true, age_seconds: Math.trunc(secondFactorAgeMinutes * 60) }
+        : undefined;
+    const defaults = {
+        organization_id: text(org?.id) ?? text(claims.org_id),
+        // Clerk's role claim is one role slug, never a list.
+        roles: bounded([org?.rol], 32, 64) ?? bounded([claims.org_role], 32, 64),
+        scopes: delimitedStrings(org?.per) ?? delimitedStrings(claims.org_permissions),
+        impersonated: actorPresent(claims.act),
+        ...(mfa ? { mfa } : {}),
+    };
+    // iat is a 60-second token refresh clock, so it is not sent as issued_at; session age is the session_created_at override.
+    return base("clerk", claims, { ...defaults, ...overrides }, { includeIssuedAt: false });
+}
+/** Map verified Auth0 ID-token, userinfo, or normalized session claims. Do not pass an opaque API access token. */
+export function fromAuth0(claims, overrides = {}) {
+    const amr = strings(claims.amr, 8, 32);
+    const mfaMethods = amr?.filter(method => method.toLowerCase() !== "pwd");
+    const defaults = {
+        organization_id: text(claims.org_id),
+        scopes: strings(claims.scope) ?? strings(claims.permissions),
+        email_verified: typeof claims.email_verified === "boolean" ? claims.email_verified : undefined,
+        phone_verified: typeof claims.phone_number_verified === "boolean" ? claims.phone_number_verified : undefined,
+        impersonated: actorPresent(claims.act),
+        ...(mfaMethods?.length ? { mfa: { present: amr?.some(method => method.toLowerCase() === "mfa") ?? false, methods: mfaMethods } } : {}),
+    };
+    return base("auth0", claims, { ...defaults, ...overrides });
+}
+/** Generic OIDC adapter for providers without a first-class helper. */
+export function fromOIDC(provider, claims, overrides = {}) {
+    if (!/^[a-z0-9][a-z0-9._-]{1,31}$/.test(provider))
+        throw new Error("provider must be a lowercase provider slug");
+    return base(provider, claims, overrides);
+}

package/dist/generated/models.d.ts

@@ -5,6 +5,8 @@ export type AssessmentRequest = {
     request_id?: string;
     deadline_ms?: number;
     response_mode?: AssessmentRequestResponseMode;
+    client_context?: AssessmentRequestClientContext;
+    auth_context?: AssessmentRequestAuthContext;
 };
 export type AssessmentRequestIdentifiers = {
     email?: string;
@@ -19,6 +21,50 @@ export type AssessmentRequestPolicyContext = {
 };
 export type AssessmentRequestPolicyContextFlow = "signup" | "login" | "recovery" | "profile_change";
 export type AssessmentRequestResponseMode = "standard" | "detailed";
+export type AssessmentRequestClientContext = {
+    timezone?: string;
+    locale?: string;
+    platform?: AssessmentRequestClientContextPlatform;
+    app_version?: string;
+    user_agent?: string;
+    device_id?: string;
+    session_id?: string;
+    form_duration_ms?: number;
+    client_observed_at?: string;
+};
+export type AssessmentRequestClientContextPlatform = "web" | "ios" | "android" | "other";
+export type AssessmentRequestAuthContext = {
+    provider: string;
+    issuer: string;
+    audience?: string;
+    audiences?: string[];
+    subject: string;
+    session_id?: string;
+    organization_id?: string;
+    tenant_id?: string;
+    token_id?: string;
+    issued_at?: string;
+    expires_at?: string;
+    session_created_at?: string;
+    auth_time?: string;
+    account_created_at?: string;
+    email_verified?: boolean;
+    phone_verified?: boolean;
+    assurance_level?: AssessmentRequestAuthContextAssuranceLevel;
+    impersonated?: boolean;
+    transport?: AssessmentRequestAuthContextTransport;
+    verified: boolean;
+    mfa?: AssessmentRequestAuthContextMfa;
+    roles?: string[];
+    scopes?: string[];
+};
+export type AssessmentRequestAuthContextAssuranceLevel = "unknown" | "low" | "medium" | "high";
+export type AssessmentRequestAuthContextTransport = "backend" | "browser";
+export type AssessmentRequestAuthContextMfa = {
+    present?: boolean;
+    methods?: string[];
+    age_seconds?: number;
+};
 export type Assessment = {
     schema_version: "1";
     assessment_id: string;
@@ -61,8 +107,8 @@ export type RiskReason = {
     weight: number;
     identifier?: ReasonIdentifier;
 };
-export type ReasonCode = "no_digital_footprint" | "voip_number" | "disposable_email" | "new_email" | "spam_reports" | "fraud_flag" | "identity_mismatch" | "country_mismatch" | "proxy_ip" | "seen_before" | "shared_ip" | "many_recent_signups" | "whatsapp_absent" | "established_accounts" | "aged_identity" | "breach_name_match" | "breach_cooccurrence" | "breach_name_mismatch" | "breach_phone_mismatch" | "recent_password_exposure" | "credential_list_exposure" | "abuse_ecosystem_member" | "no_breach_history";
-export type ReasonIdentifier = "email" | "username" | "phone" | "name" | "ip";
+export type ReasonCode = "no_digital_footprint" | "voip_number" | "disposable_email" | "new_email" | "spam_reports" | "fraud_flag" | "identity_mismatch" | "country_mismatch" | "proxy_ip" | "seen_before" | "shared_ip" | "many_recent_signups" | "established_accounts" | "aged_identity" | "breach_name_match" | "breach_cooccurrence" | "breach_name_mismatch" | "breach_phone_mismatch" | "recent_password_exposure" | "credential_list_exposure" | "abuse_ecosystem_member" | "no_breach_history" | "automation_fast_submit" | "client_clock_skew" | "bot_or_automation" | "auth_email_verified" | "auth_phone_verified" | "auth_mfa_recent" | "auth_new_session" | "auth_new_account" | "auth_impersonated" | "context_timezone_mismatch" | "context_locale_mismatch" | "context_line_country_mismatch" | "prior_abuse_link";
+export type ReasonIdentifier = "email" | "username" | "phone" | "name" | "ip" | "context";
 export type RiskSummary = {
     phone?: RiskSummaryPhone;
     email?: RiskSummaryEmail;
@@ -73,7 +119,6 @@ export type RiskSummary = {
 export type RiskSummaryPhone = {
     line_type?: RiskSummaryPhoneLineType;
     country?: string;
-    on_whatsapp?: boolean;
     report_count?: number;
     carrier?: string;
 };
@@ -246,3 +291,16 @@ export type AssessmentQueryResponseMode = "standard" | "detailed";
 export type WebhookVerificationResponse = {
     challenge: string;
 };
+export type AssessmentOutcomeRequest = {
+    outcome: Outcome;
+    observed_at?: string;
+    external_ref?: string;
+    notes?: string;
+};
+export type Outcome = "confirmed_abuse" | "account_takeover" | "chargeback" | "false_positive" | "legitimate" | "unknown";
+export type AssessmentOutcome = {
+    id: string;
+    assessment_id: string;
+    outcome: Outcome;
+    received_at: string;
+};

package/dist/generated/models.js

@@ -1,2 +1,2 @@
-/* GENERATED FILE. Run python3 sdks/tools/generate_models.py to update. */
+/* GENERATED FILE. Run python3 apps/identity-intelligence/sdks/tools/generate_models.py to update. */
 export {};

package/dist/index.d.ts

@@ -1,45 +1,82 @@
 /** Server-side NoResponse signup client. Never expose the API key in browser code. */
-import type { Assessment, AssessmentList, AssessmentQuery, AssessmentRequest } from "./generated/models.js";
+import type { Assessment, AssessmentList, AssessmentOutcome, AssessmentQuery, AssessmentRequest, Outcome } from "./generated/models.js";
 export type * from "./generated/models.js";
 export { verifyWebhook, webhookAssessment, webhookVerificationResponse } from "./webhooks.js";
-/** standard or detailed; raw is never served. Derived from the generated request type. */
+export { fromAuth0, fromClerk, fromOIDC, fromWorkOS } from "./auth.js";
 export type ResponseMode = NonNullable<AssessmentRequest["response_mode"]>;
+export type Flow = NonNullable<NonNullable<AssessmentRequest["policy_context"]>["flow"]>;
 export declare class NoResponseError extends Error {
     readonly status: number;
     readonly type?: string | undefined;
     readonly code?: string | undefined;
     readonly detail?: string | undefined;
-    constructor(status: number, message: string, type?: string | undefined, code?: string | undefined, detail?: string | undefined);
+    readonly requestId?: string;
+    readonly retryAfter?: number;
+    readonly retryable: boolean;
+    constructor(status: number, message: string, type?: string | undefined, code?: string | undefined, detail?: string | undefined, metadata?: {
+        requestId?: string;
+        retryAfter?: number;
+    });
 }
+export type NoResponseConfig = {
+    apiKey: string;
+    baseUrl: string;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+    /** Safe retries for network errors, 429 and 503. POST assessment retries reuse the same Idempotency-Key. */
+    maxRetries?: number;
+    /** Base delay for a transient retry when Retry-After is absent. */
+    retryBaseDelayMs?: number;
+};
 export declare class NoResponse {
     private readonly config;
     private readonly baseUrl;
-    constructor(config: {
-        apiKey: string;
-        baseUrl: string;
-        fetch?: typeof fetch;
-        timeoutMs?: number;
-    });
+    constructor(config: NoResponseConfig);
     assess(input: {
         accountId: string;
         email?: string;
         username?: string;
         phone?: string;
-        /** Full name as typed. Used only for matching; never looked up. Needs email, username or phone. */
         name?: string;
-        /** Signup IPv4 or IPv6 address (public ranges only). Needs email, username or phone. */
         ip?: string;
-        requestId?: string;
+        /** Customer event policy. Defaults to signup when omitted. */
+        flow?: Flow;
+        /** ISO 3166-1 alpha-2 region used for consistency checks. */
         region?: string;
+        requestId?: string;
         deadlineMs?: number;
         responseMode?: ResponseMode;
+        /** Bounded, tenant-scoped client hints. Raw user agents and opaque IDs are never returned. */
+        clientContext?: AssessmentRequest["client_context"];
+        /** Normalized claims from a provider-verified backend session. Never pass a raw token. */
+        authContext?: AssessmentRequest["auth_context"];
         idempotencyKey: string;
     }): Promise<Assessment>;
     getAssessment(assessmentId: string, options?: {
         responseMode?: ResponseMode;
     }): Promise<Assessment>;
+    private getAssessmentWithHeaders;
+    waitForAssessment(assessmentId: string, options?: {
+        responseMode?: ResponseMode;
+        timeoutMs?: number;
+    }): Promise<Assessment>;
     queryAssessments(query: AssessmentQuery & {
         responseMode?: ResponseMode;
     }): Promise<AssessmentList>;
+    /**
+     * Report what was later learned about an assessed account. confirmed_abuse, account_takeover and
+     * chargeback report abuse; false_positive and legitimate withdraw this tenant's earlier report;
+     * unknown is recorded only. A retry with the same idempotencyKey and body answers the same record.
+     */
+    recordOutcome(assessmentId: string, input: {
+        outcome: Outcome;
+        /** RFC 3339 time the provider observed the outcome; defaults to when NoResponse receives it. */
+        observedAt?: string;
+        externalRef?: string;
+        notes?: string;
+        idempotencyKey: string;
+    }): Promise<AssessmentOutcome>;
+    private validateMode;
     private request;
+    private waitForRetry;
 }

package/dist/index.js

@@ -1,18 +1,30 @@
 export { verifyWebhook, webhookAssessment, webhookVerificationResponse } from "./webhooks.js";
+export { fromAuth0, fromClerk, fromOIDC, fromWorkOS } from "./auth.js";
 const LOOKUP_IDENTIFIERS = ["email", "username", "phone"];
 const MATCH_IDENTIFIERS = ["name", "ip"];
+const IDEMPOTENCY = /^[A-Za-z0-9._:-]{16,128}$/;
+const ASSESSMENT_ID = /^asm_[0-9A-HJKMNP-TV-Z]{26}$/;
+const OUTCOMES = ["confirmed_abuse", "account_takeover", "chargeback", "false_positive", "legitimate", "unknown"];
+const EXTERNAL_REF = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const RFC3339 = /^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\.[0-9]+)?(?:Z|[+-][0-9]{2}:[0-9]{2})$/;
 export class NoResponseError extends Error {
     status;
     type;
     code;
     detail;
-    constructor(status, message, type, code, detail) {
+    requestId;
+    retryAfter;
+    retryable;
+    constructor(status, message, type, code, detail, metadata = {}) {
         super(message);
         this.status = status;
         this.type = type;
         this.code = code;
         this.detail = detail;
         this.name = "NoResponseError";
+        this.requestId = metadata.requestId;
+        this.retryAfter = metadata.retryAfter;
+        this.retryable = status === 429 || status === 503;
     }
 }
 export class NoResponse {
@@ -25,10 +37,15 @@ export class NoResponse {
         if (config.timeoutMs !== undefined && (!Number.isInteger(config.timeoutMs) || config.timeoutMs <= 0)) {
             throw new Error("timeoutMs must be a positive integer");
         }
+        if (config.maxRetries !== undefined && (!Number.isInteger(config.maxRetries) || config.maxRetries < 0)) {
+            throw new Error("maxRetries must be a non-negative integer");
+        }
+        if (config.retryBaseDelayMs !== undefined && (!Number.isInteger(config.retryBaseDelayMs) || config.retryBaseDelayMs < 0)) {
+            throw new Error("retryBaseDelayMs must be a non-negative integer");
+        }
         const url = new URL(config.baseUrl);
-        if (url.search || url.hash || /[?#]$/.test(config.baseUrl)) {
+        if (url.search || url.hash || /[?#]$/.test(config.baseUrl))
             throw new Error("baseUrl must not include a query or fragment");
-        }
         if (url.protocol !== "https:" && url.hostname !== "localhost" && url.hostname !== "127.0.0.1") {
             throw new Error("NoResponse requires HTTPS outside localhost");
         }
@@ -46,41 +63,77 @@ export class NoResponse {
                 identifiers[key] = input[key];
         if (input.name !== undefined && (input.name.length < 1 || input.name.length > 128))
             throw new Error("name must be 1-128 characters");
-        if (!/^[A-Za-z0-9._:-]{16,128}$/.test(input.idempotencyKey))
+        if (!IDEMPOTENCY.test(input.idempotencyKey))
             throw new Error("Valid 16-128 character idempotencyKey required");
+        if (input.deadlineMs !== undefined && (!Number.isInteger(input.deadlineMs) || input.deadlineMs < 50 || input.deadlineMs > 500)) {
+            throw new Error("deadlineMs must be 50–500");
+        }
+        if (input.region !== undefined && !/^[A-Z]{2}$/.test(input.region))
+            throw new Error("region must be an uppercase ISO alpha-2 code");
+        if (input.responseMode !== undefined && input.responseMode !== "standard" && input.responseMode !== "detailed") {
+            throw new Error("responseMode must be standard or detailed; raw is never served");
+        }
         const body = { account_id: input.accountId, identifiers: identifiers };
         if (input.requestId !== undefined)
             body.request_id = input.requestId;
-        if (input.deadlineMs !== undefined) {
-            if (!Number.isInteger(input.deadlineMs) || input.deadlineMs < 50 || input.deadlineMs > 500)
-                throw new Error("deadlineMs must be 50–500");
+        if (input.deadlineMs !== undefined)
             body.deadline_ms = input.deadlineMs;
+        if (input.flow !== undefined || input.region !== undefined) {
+            body.policy_context = { flow: input.flow ?? "signup", ...(input.region !== undefined ? { region: input.region } : {}) };
         }
-        if (input.region !== undefined)
-            body.policy_context = { flow: "signup", region: input.region };
-        if (input.responseMode !== undefined) {
-            if (input.responseMode !== "standard" && input.responseMode !== "detailed")
-                throw new Error("responseMode must be standard or detailed; raw is never served");
+        if (input.responseMode !== undefined)
             body.response_mode = input.responseMode;
-        }
-        return this.request("/v1/assessments", { method: "POST", body: JSON.stringify(body), headers: { "Idempotency-Key": input.idempotencyKey } });
+        if (input.clientContext !== undefined)
+            body.client_context = input.clientContext;
+        if (input.authContext !== undefined)
+            body.auth_context = input.authContext;
+        return this.request("/v1/assessments", {
+            method: "POST", body: JSON.stringify(body), headers: { "Idempotency-Key": input.idempotencyKey },
+        });
     }
     async getAssessment(assessmentId, options = {}) {
-        if (!/^asm_[0-9A-HJKMNP-TV-Z]{26}$/.test(assessmentId))
+        if (!ASSESSMENT_ID.test(assessmentId))
             throw new Error("Invalid assessment ID");
-        if (options.responseMode !== undefined && options.responseMode !== "standard" && options.responseMode !== "detailed")
-            throw new Error("responseMode must be standard or detailed");
+        this.validateMode(options.responseMode);
         const suffix = options.responseMode ? `?response_mode=${options.responseMode}` : "";
         return this.request(`/v1/assessments/${assessmentId}${suffix}`, { method: "GET" });
     }
+    async getAssessmentWithHeaders(assessmentId, options = {}) {
+        if (!ASSESSMENT_ID.test(assessmentId))
+            throw new Error("Invalid assessment ID");
+        this.validateMode(options.responseMode);
+        const suffix = options.responseMode ? `?response_mode=${options.responseMode}` : "";
+        let retryAfter;
+        const assessment = await this.request(`/v1/assessments/${assessmentId}${suffix}`, {
+            method: "GET",
+            onResponse: (headers) => { retryAfter = parseRetryAfter(headers.get("Retry-After")); },
+        });
+        return { assessment, retryAfter };
+    }
+    async waitForAssessment(assessmentId, options = {}) {
+        const timeoutMs = options.timeoutMs ?? 30_000;
+        if (!Number.isInteger(timeoutMs) || timeoutMs <= 0)
+            throw new Error("wait timeoutMs must be a positive integer");
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            const { assessment, retryAfter } = await this.getAssessmentWithHeaders(assessmentId, options);
+            if (assessment.status !== "pending")
+                return assessment;
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                throw new Error("Timed out waiting for assessment");
+            const delay = retryAfter === undefined ? 500 : retryAfter * 1000;
+            await new Promise((resolve) => setTimeout(resolve, Math.min(delay, remaining)));
+        }
+    }
     async queryAssessments(query) {
-        if (!query.account_id || (query.limit !== undefined && (!Number.isInteger(query.limit) || query.limit < 1 || query.limit > 50)))
+        if (!query.account_id || (query.limit !== undefined && (!Number.isInteger(query.limit) || query.limit < 1 || query.limit > 50))) {
             throw new Error("Invalid assessment query");
+        }
         if (query.responseMode !== undefined && query.response_mode !== undefined)
             throw new Error("Supply only one response mode");
         const mode = query.responseMode ?? query.response_mode;
-        if (mode !== undefined && mode !== "standard" && mode !== "detailed")
-            throw new Error("responseMode must be standard or detailed; raw is never served");
+        this.validateMode(mode);
         const body = { account_id: query.account_id };
         if (query.limit !== undefined)
             body.limit = query.limit;
@@ -90,37 +143,102 @@ export class NoResponse {
             body.response_mode = mode;
         return this.request("/v1/assessments/query", { method: "POST", body: JSON.stringify(body) });
     }
+    /**
+     * Report what was later learned about an assessed account. confirmed_abuse, account_takeover and
+     * chargeback report abuse; false_positive and legitimate withdraw this tenant's earlier report;
+     * unknown is recorded only. A retry with the same idempotencyKey and body answers the same record.
+     */
+    async recordOutcome(assessmentId, input) {
+        if (!ASSESSMENT_ID.test(assessmentId))
+            throw new Error("Invalid assessment ID");
+        if (!OUTCOMES.includes(input.outcome))
+            throw new Error(`outcome must be one of ${OUTCOMES.join(", ")}`);
+        if (!IDEMPOTENCY.test(input.idempotencyKey))
+            throw new Error("Valid 16-128 character idempotencyKey required");
+        if (input.observedAt !== undefined && !RFC3339.test(input.observedAt))
+            throw new Error("observedAt must be an RFC 3339 time");
+        if (input.externalRef !== undefined && !EXTERNAL_REF.test(input.externalRef))
+            throw new Error("externalRef must be 1-128 safe characters");
+        if (input.notes !== undefined && (input.notes.length < 1 || [...input.notes].length > 500))
+            throw new Error("notes must be 1-500 characters");
+        const body = { outcome: input.outcome };
+        if (input.observedAt !== undefined)
+            body.observed_at = input.observedAt;
+        if (input.externalRef !== undefined)
+            body.external_ref = input.externalRef;
+        if (input.notes !== undefined)
+            body.notes = input.notes;
+        return this.request(`/v1/assessments/${assessmentId}/outcomes`, {
+            method: "POST", body: JSON.stringify(body), headers: { "Idempotency-Key": input.idempotencyKey },
+        });
+    }
+    validateMode(mode) {
+        if (mode !== undefined && mode !== "standard" && mode !== "detailed")
+            throw new Error("responseMode must be standard or detailed; raw is never served");
+    }
     async request(path, options) {
         const transport = this.config.fetch ?? fetch;
-        const response = await transport(this.baseUrl + path, {
-            method: options.method,
-            headers: {
-                Authorization: `Bearer ${this.config.apiKey}`,
-                Accept: "application/json",
-                ...(options.body ? { "Content-Type": "application/json" } : {}),
-                ...options.headers,
-            },
-            body: options.body,
-            signal: AbortSignal.timeout(this.config.timeoutMs ?? 5000),
-        });
-        if (!response.ok) {
-            let problem = {};
+        const maxRetries = this.config.maxRetries ?? 2;
+        const baseDelay = this.config.retryBaseDelayMs ?? 100;
+        let lastError;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            let response;
             try {
-                const parsed = await response.json();
-                if (parsed !== null && typeof parsed === "object") {
-                    const body = parsed;
-                    problem = {
-                        ...(typeof body.type === "string" ? { type: body.type } : {}),
-                        ...(typeof body.code === "string" ? { code: body.code } : {}),
-                        ...(typeof body.detail === "string" ? { detail: body.detail } : {}),
-                    };
-                }
+                response = await transport(this.baseUrl + path, {
+                    method: options.method,
+                    headers: {
+                        Authorization: `Bearer ${this.config.apiKey}`,
+                        Accept: "application/json",
+                        ...(options.body ? { "Content-Type": "application/json" } : {}),
+                        ...options.headers,
+                    },
+                    body: options.body,
+                    signal: AbortSignal.timeout(this.config.timeoutMs ?? 5000),
+                });
             }
-            catch {
-                // Preserve NoResponseError when the error body is empty or invalid JSON.
+            catch (error) {
+                lastError = error;
+                if (attempt >= maxRetries)
+                    throw error;
+                await this.waitForRetry(attempt, undefined, baseDelay);
+                continue;
             }
-            throw new NoResponseError(response.status, `NoResponse request failed (HTTP ${response.status})`, problem.type, problem.code, problem.detail);
+            if (!response.ok) {
+                let problem = {};
+                try {
+                    const parsed = await response.json();
+                    if (parsed !== null && typeof parsed === "object") {
+                        const body = parsed;
+                        problem = {
+                            ...(typeof body.type === "string" ? { type: body.type } : {}),
+                            ...(typeof body.code === "string" ? { code: body.code } : {}),
+                            ...(typeof body.detail === "string" ? { detail: body.detail } : {}),
+                            ...(typeof body.request_id === "string" ? { request_id: body.request_id } : {}),
+                        };
+                    }
+                }
+                catch { /* preserve the typed error for malformed bodies */ }
+                const retryAfter = parseRetryAfter(response.headers.get("Retry-After"));
+                const error = new NoResponseError(response.status, `NoResponse request failed (HTTP ${response.status})`, problem.type, problem.code, problem.detail, { requestId: problem.request_id ?? response.headers.get("X-Request-ID") ?? undefined, retryAfter });
+                lastError = error;
+                if (attempt < maxRetries && error.retryable) {
+                    await this.waitForRetry(attempt, retryAfter, baseDelay);
+                    continue;
+                }
+                throw error;
+            }
+            options.onResponse?.(response.headers);
+            return response.json();
         }
-        return response.json();
+        throw lastError instanceof Error ? lastError : new Error("NoResponse request failed");
+    }
+    async waitForRetry(attempt, retryAfter, baseDelay) {
+        const delay = retryAfter !== undefined ? retryAfter * 1000 : baseDelay * (2 ** Math.min(attempt, 6));
+        await new Promise((resolve) => setTimeout(resolve, delay));
     }
 }
+function parseRetryAfter(value) {
+    if (!value || !/^[1-9][0-9]{0,3}$/.test(value))
+        return undefined;
+    return Number(value);
+}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@noresponse/node",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "description": "Server-only NoResponse signup and webhook SDK",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/noresponsehq/noresponse.git",
-    "directory": "sdks/typescript"
+    "directory": "apps/identity-intelligence/sdks/typescript"
   },
   "engines": {
     "node": ">=20"