@anis-ly/partners 0.0.0-stage → 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1053 @@
+import { inspect } from 'node:util';
+
+/**
+ * The narrow key-custody seam: sign exact bytes and return ECDSA P-256 / SHA-256 in IEEE P1363 r‖s form.
+ *
+ * @remarks Accepting bytes instead of a key object lets a partner keep keys in its own vault or HSM. Exactly 64
+ * bytes prevent DER's alternate encoding of a mathematically valid signature from reaching Anis as a request error.
+ */
+interface P256Signer {
+    /** Signs these bytes and returns exactly 64 bytes; DER has a different wire form and Anis refuses it. */
+    sign(data: Uint8Array): Promise<Uint8Array>;
+}
+/** A signer identified by the credential that Anis issued at enrollment. */
+interface RequestSigner extends P256Signer {
+    /** The canonical request key ID; treating it as an identifier avoids late authentication failures. */
+    readonly keyId: string;
+}
+
+/**
+ * Associates an external signer with the credential UUID used in request signatures.
+ *
+ * @remarks Keeping key custody behind the byte-signing seam lets a partner use a vault or HSM without exporting its
+ * private key into this process.
+ */
+declare class KeyedSigner implements RequestSigner {
+    private readonly signer;
+    /** The enrolled credential identifier, canonicalized so Anis can resolve it. */
+    readonly keyId: string;
+    /** Creates a binding; canonical identity avoids a valid signature that names an unknown credential. */
+    constructor(signer: P256Signer, keyId: string);
+    /** Signs exact bytes through partner-owned key custody without exposing key material. */
+    sign(data: Uint8Array): Promise<Uint8Array>;
+}
+
+/**
+ * One public key published for verifying Partner responses.
+ *
+ * @remarks Active, next, and retiring versions are published together so a response around a key rotation can still
+ * be verified without trusting a key supplied by that response.
+ */
+interface PartnerJwk {
+    /** Key type; only EC keys can be imported by the response verifier. */ kty?: string;
+    /** Curve; only P-256 matches the algorithm Anis uses for response signatures. */ crv?: string;
+    /** Base64url X coordinate; it must decode to 32 bytes for a P-256 point. */ x?: string;
+    /** Base64url Y coordinate; both coordinates are required to validate the published point. */ y?: string;
+    /** Response key version identifier used to find the key named by a response. */ kid?: string;
+    /** Intended use when published; retained so the document is represented faithfully. */ use?: string;
+    /** Algorithm when published; retained for partner inspection and protocol compatibility. */ alg?: string;
+    /** Private scalar; a non-empty value means the whole document has exposed private key material. */ d?: string;
+}
+/** Published response verification key set; rotation versions are needed to verify answers during key changes. */
+interface SigningKeySet {
+    /** Active, next, and retiring public key versions published together for safe rotation. */
+    keys: readonly PartnerJwk[];
+}
+
+/**
+ * Signs with a P-256 PKCS#8 key held in this process.
+ *
+ * @remarks This file-backed option is suitable when the host protects the key file; `P256Signer` remains the seam for
+ * a vault or HSM that never releases key material.
+ */
+declare class PemP256Signer implements P256Signer {
+    #private;
+    private readonly publicKey;
+    private constructor();
+    /** Imports a PKCS#8 PEM key and refuses other curves at load time, before a partner receives an avoidable refusal. */
+    static fromPem(pem: string): Promise<PemP256Signer>;
+    /** Reads and imports a protected PKCS#8 PEM file so the private key can remain in host-controlled storage. */
+    static fromPemFile(path: string): Promise<PemP256Signer>;
+    /** Signs bytes in WebCrypto's 64-byte P1363 form; no DER conversion can silently change the wire signature. */
+    sign(data: Uint8Array): Promise<Uint8Array>;
+    /** Exports only public coordinates for enrollment and verification; the private half is never part of the JWK. */
+    publicJwk(): Promise<PartnerJwk>;
+    /** Binds this key to the issued credential UUID used by Anis to resolve request signatures. */
+    forKey(keyId: string): KeyedSigner;
+}
+
+/** Base type for failures raised by this SDK, so applications can handle local faults separately from HTTP refusals. */
+declare class AnisPartnersError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+    static [Symbol.hasInstance](value: unknown): boolean;
+    [inspect.custom](): string;
+}
+
+/** Indicates signing failed before a request was sent, so the partner can safely distinguish it from a server outcome. */
+declare class RequestSigningError extends AnisPartnersError {
+    /** Preserves the original signer failure as `cause` while keeping sensitive signature material out of the message. */
+    constructor(cause: unknown);
+}
+
+/**
+ * Computes the RFC 7638 fingerprint used to confirm the submitted key.
+ *
+ * @remarks Computing locally and comparing with Anis's answer catches a changed public key before a partner proves
+ * possession of the wrong key.
+ */
+declare function keyThumbprint(publicJwk: PartnerJwk): string;
+
+/** Converts a locally checked thumbprint into the code read to Anis staff. */
+declare function safetyCodeFromThumbprint(thumbprint: string): string;
+
+/**
+ * Domain separator checked by Anis when verifying credential possession.
+ *
+ * @remarks Including a distinct first line prevents a credential proof from being reused as another signature type.
+ */
+declare const DOMAIN_SEPARATOR = "anis.partners.v2.credential-proof";
+/** Builds the exact domain-separated UTF-8 proof message so both sides hash the challenge and bind the same credential. */
+declare function proofMessage(keyId: string, challengeGeneration: number, challenge: string, thumbprint: string): Uint8Array;
+/** Signs the proof message and returns unpadded base64url P1363 bytes; DER would be refused at the proof endpoint. */
+declare function proofSignature(message: Uint8Array, signer: P256Signer): Promise<string>;
+
+/** Invitation state as reported by the enrollment surface. */
+interface EnrollmentState {
+    /** Invitation UUID, when known. */
+    invitationId?: string;
+    /** Application UUID being enrolled. */
+    applicationId?: string;
+    /** Current invitation workflow state. */
+    state?: string;
+    /** Invitation expiry instant. */
+    expiresAt?: Date;
+}
+/**
+ * Public key and requested validity window submitted during enrollment.
+ *
+ * @remarks Submit only the public half: sending private key material is refused by Anis and would expose signing
+ * credentials outside the partner's key custody.
+ */
+interface EnrollmentKeyRequest {
+    /** Public P-256 JWK only; private members are refused by Anis. */
+    publicJwk: PartnerJwk;
+    /** Requested beginning of the validity window. */
+    notBefore: Date;
+    /** Requested end of the validity window. */
+    expiresAt: Date;
+}
+/**
+ * Key submission answer containing the challenge that must be signed.
+ *
+ * @remarks The local thumbprint check ties Anis's challenge and safety code to the key the partner actually submitted;
+ * do not trust a safety code copied from an unverified answer.
+ */
+interface EnrollmentKeyResult {
+    /** Credential UUID that becomes the request key id when active. */
+    keyId: string;
+    /** Server-computed RFC 7638 thumbprint, compared against the submitted public key. */
+    thumbprint?: string;
+    /** Safety code derived locally from the verified key thumbprint. */
+    safetyCode?: string;
+    /** Challenge whose domain-separated message proves possession of the private key. */
+    challenge?: string;
+    /** Challenge generation, incremented when Anis reissues the challenge. */
+    challengeGeneration?: number;
+}
+/** Proof request for the current enrollment challenge generation. */
+interface EnrollmentProofRequest {
+    /** Credential UUID whose challenge is being answered. */
+    keyId: string;
+    /** Generation that Anis currently expects. */
+    challengeGeneration: number;
+    /** P-256/P1363 signature in unpadded base64url form. */
+    signature: string;
+}
+/**
+ * Enrollment proof and staff-approval state.
+ *
+ * @remarks A successful proof can remain pending until Anis staff verify the safety code. That approval is a control
+ * on activation, not a state to work around.
+ */
+interface EnrollmentStatus {
+    /** Credential UUID, when the invitation has accepted a key. */
+    keyId?: string;
+    /** Current challenge generation. */
+    challengeGeneration?: number;
+    /** Proof workflow state. */
+    proofState?: string;
+    /** Staff approval state. */
+    approvalState?: string;
+    /** Overall enrollment state. */
+    state?: string;
+    /** Current workflow-step expiry instant. */
+    expiresAt?: Date;
+    /** Credential validity end instant after activation. */
+    keyExpiresAt?: Date;
+}
+/** Facts the signature self-check reports about how the gateway interpreted a request. */
+interface SignatureDiagnostic {
+    /** Matched route identifier. */
+    routeId?: string;
+    /** HTTP method received by the gateway. */
+    method?: string;
+    /** Authority received by the gateway. */
+    authority?: string;
+    /** Path received by the gateway. */
+    path?: string;
+    /** Query without its leading question mark. */
+    canonicalQuery?: string;
+    /** Kind assigned by the route table. */
+    requestKind?: string;
+    /** Required permission for the route. */
+    requiredScope?: string;
+    /** Covered components required by the matched profile. */
+    coveredComponents: readonly string[];
+    /** Credential UUID named by the request. */
+    keyId?: string;
+    /** Partner UUID resolved from that credential. */
+    partnerId?: string;
+    /** Application UUID resolved from that credential. */
+    applicationId?: string;
+    /** Policy version applied. */
+    policyVersion?: number;
+    /** Scopes currently in effect. */
+    effectiveScopes: readonly string[];
+    /** Instant the gateway received the request. */
+    receivedAt?: Date;
+}
+
+/** Cancellation passed to signing-key retrieval during a caller's API operation. */
+interface SigningKeyRequestOptions {
+    /** Stops waiting for or fetching a key document when the owning API call is canceled. */
+    signal?: AbortSignal;
+}
+/** Supplies published keys separately from verification so key rotation stays out of signature-check logic. */
+interface SigningKeySource {
+    /** Returns the cached key document or fetches it on first use. */
+    get(options?: SigningKeyRequestOptions): Promise<SigningKeySet>;
+    /** Fetches once after an unknown key so hostile key IDs cannot trigger unbounded requests. */
+    refresh(options?: SigningKeyRequestOptions): Promise<SigningKeySet>;
+}
+
+/** Optional shared cache for serverless instances that do not retain process memory between requests. */
+interface KeyDocumentCache {
+    /** Reads a cached document by stable authority key so another instance can avoid a duplicate fetch. */
+    get(key: string): Promise<string | undefined>;
+    /** Stores the public document for the requested lifetime. */
+    set(key: string, value: string, ttlSeconds: number): Promise<void>;
+}
+
+/** Structured partner logger; fields contain stable identifiers and never request secrets. */
+interface PartnerLogger {
+    /** Emits a diagnostic event. */
+    debug(message: string, fields: Record<string, unknown>): void | Promise<void>;
+    /** Emits an informational event. */
+    info(message: string, fields: Record<string, unknown>): void | Promise<void>;
+    /** Emits a refusal or retry guidance event. */
+    warn(message: string, fields: Record<string, unknown>): void | Promise<void>;
+    /** Emits a discarded-response or communication error. */
+    error(message: string, fields: Record<string, unknown>): void | Promise<void>;
+}
+
+/** Settings for an enrollment invitation before an active request key exists. */
+interface AnisEnrollmentClientOptions {
+    /** Issued Anis authority. */
+    authority: string | URL;
+    /** Invitation UUID being enrolled. */
+    invitationId: string;
+    /** Secret invitation token; it is sent only in Authorization and never logged. */
+    enrollmentToken: string;
+    /** Injectable fetch for proxies and in-memory API doubles. */
+    fetch?: typeof globalThis.fetch | undefined;
+    /** Shared key-document cache for short-lived hosts. */
+    keyCache?: KeyDocumentCache | undefined;
+    /** Optional structured log sink. */
+    logger?: Partial<PartnerLogger> | undefined;
+    /** Cache lifetime for the unsigned public response-key document. */
+    signingKeyCacheSeconds?: number | undefined;
+    /** Per-request timeout. */
+    timeoutMs?: number | undefined;
+}
+/** Raised when the verified challenge names a different key than the one submitted. */
+declare class EnrollmentKeyMismatchError extends AnisPartnersError {
+    /** Thumbprint calculated from the public key submitted by this caller. */
+    readonly localThumbprint: string;
+    /** Thumbprint returned by Anis, when present. */
+    readonly serverThumbprint?: string;
+    /** Stops a proof from being made with a challenge bound to another key. */
+    constructor(localThumbprint: string, serverThumbprint?: string);
+}
+/** Enrollment flow, authenticated by its one-time token and still verifying every answer. */
+declare class AnisEnrollmentClient {
+    #private;
+    private readonly transport;
+    private readonly invitation;
+    private constructor();
+    /** Creates an enrollment client over the same mandatory response-verification pipeline. */
+    static create(input: AnisEnrollmentClientOptions): AnisEnrollmentClient;
+    /** Reads invitation state. */
+    get(options?: {
+        signal?: AbortSignal;
+    }): Promise<EnrollmentState>;
+    /** Reads approval and key-expiry state. */
+    getStatus(options?: {
+        signal?: AbortSignal;
+    }): Promise<EnrollmentStatus>;
+    /** Submits a public key, then checks the verified answer against its local RFC 7638 thumbprint. */
+    submitKey(request: EnrollmentKeyRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<EnrollmentKeyResult>;
+    /** Builds the possession message, obtains its P-256 signature, and submits the proof. */
+    prove(submitted: EnrollmentKeyResult, signer: P256Signer, options?: {
+        signal?: AbortSignal;
+    }): Promise<EnrollmentStatus>;
+    /** Submits a previously prepared proof for the current challenge generation. */
+    submitProof(request: EnrollmentProofRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<EnrollmentStatus>;
+}
+
+/** Every published error code this SDK version recognizes. */
+declare const ERROR_CODES: readonly ["account_inactive", "allowed_debt_consent_required", "binding_not_authorized", "business_subscription_required", "card_not_found", "card_unavailable", "challenge_expired", "currency_not_supported", "daily_limit_exceeded", "dependency_unavailable", "idempotency_conflict", "insufficient_balance", "insufficient_scope", "internal_error", "invalid_content_digest", "invalid_credentials", "invitation_invalid", "invoice_reveal_limit_exceeded", "key_duplicate", "key_proof_invalid", "malformed_signed_request", "operation_processing", "owner_limit_exceeded", "price_changed", "purchase_not_allowed", "quantity_unavailable", "rate_limited", "replay_detected", "request_timeout", "resource_not_found", "reveal_not_allowed", "signature_expired", "source_ip_not_allowed", "validation_failed", "wallet_disabled", "wallet_expired", "wallet_not_granted"];
+/** A published error code, or unknown when Anis adds one this SDK has not seen yet. */
+type ErrorCode = (typeof ERROR_CODES)[number] | 'unknown';
+
+/** RFC 9457 problem returned for a verified refusal. Branch on code, never localized title or detail. */
+interface Problem {
+    /** Permanent documentation URI for this error. */
+    type?: string;
+    /** Localized presentation text. */
+    title?: string;
+    /** HTTP status repeated in the body. */
+    status: number;
+    /** Localized presentation detail. */
+    detail?: string;
+    /** Machine code used for stable decisions. */
+    code?: string;
+    /** Correlation id to quote when asking Anis about this call. */
+    requestId?: string;
+    /** Documented per-code extensions retained without assuming their shape. */
+    extensions?: unknown;
+}
+
+/** Whether Anis's refusal means the order is closed or may still complete. */
+type OrderRefusalOutcome = 'notPlaced' | 'unknown';
+/** An Anis API refusal with stable machine fields for partner-side branching. */
+declare class AnisApiError extends AnisPartnersError {
+    /** Complete parsed problem returned by Anis. */
+    readonly problem: Problem;
+    /** Known machine code, or unknown when this SDK has not seen the value. */
+    readonly code: ErrorCode;
+    /** Exact wire code, including an unknown future value. */
+    readonly rawCode?: string;
+    /** HTTP status of the verified response. */
+    readonly status: number;
+    /** Correlation id to quote when asking Anis about the call. */
+    readonly requestId?: string;
+    /** Permanent documentation link for this code. */
+    readonly typeUri?: string;
+    /** Signed Retry-After value in seconds, when supplied. */
+    readonly retryAfter?: number;
+    /** True when Anis returned the recorded refusal for this operation id. */
+    readonly isReplayed: boolean;
+    /** Whether the catalogue marks this code retryable; this does not decide order recovery. */
+    readonly isRetryable: boolean;
+    /** Whether the refusal leaves an order open for resume. */
+    readonly orderOutcome: OrderRefusalOutcome;
+    /**
+     * Creates a structured API error from a verified problem.
+     *
+     * @remarks The code is the stable branching contract. Titles and details change with language and copy updates, so
+     * callers that branch on the message can break without any API behavior changing.
+     */
+    constructor(problem: Problem, status: number, retryAfter?: number, isReplayed?: boolean);
+}
+/** A final refusal because the wallet balance cannot cover the order. */
+declare class InsufficientBalanceError extends AnisApiError {
+}
+/** A final refusal because the catalogue price changed after it was read. */
+declare class PriceChangedError extends AnisApiError {
+}
+/** A final refusal because the card or requested quantity is unavailable. */
+declare class OutOfStockError extends AnisApiError {
+}
+/** A final refusal because an operation id was reused for a different order. */
+declare class IdempotencyConflictError extends AnisApiError {
+}
+/** A request-rate refusal; callers should honor Retry-After when present. */
+declare class RateLimitedError extends AnisApiError {
+}
+/** A final refusal because an owner spending allowance is exhausted. */
+declare class LimitExceededError extends AnisApiError {
+}
+/** A refusal because the signing credentials are not accepted. */
+declare class InvalidCredentialsError extends AnisApiError {
+}
+/** A refusal because the same signed nonce was already received. */
+declare class ReplayDetectedError extends AnisApiError {
+}
+/** A refusal because current application or owner policy does not allow the call. */
+declare class AuthorizationError extends AnisApiError {
+}
+/** A refusal for a resource that is absent or intentionally indistinguishable from absent. */
+declare class ResourceNotFoundError extends AnisApiError {
+}
+/** A refusal because the request does not satisfy the published contract. */
+declare class ValidationFailedError extends AnisApiError {
+}
+/** A refusal where Anis could not reach a decision; an order may still complete. */
+declare class DependencyUnavailableError extends AnisApiError {
+}
+/** A refusal of an invitation, key submission, or enrollment proof step. */
+declare class EnrollmentRefusedError extends AnisApiError {
+}
+
+/** Describes a local private-key loading or signing failure without exposing private key material. */
+declare class PrivateKeyError extends AnisPartnersError {
+}
+
+/** A signed answer violated a model contract; its content is deliberately absent from the message and cause. */
+declare class MalformedResponseError extends AnisPartnersError {
+    readonly model: string;
+    constructor(model: string);
+}
+
+/** The public signing-key document could not be loaded, so the response has no usable verification key set. */
+declare class SigningKeyDocumentUnavailableError extends AnisPartnersError {
+    constructor();
+}
+
+/**
+ * Closed set of reasons a signed response is discarded.
+ *
+ * @remarks A response that cannot be verified is never returned for use; stable reasons let a partner handle a
+ * refusal without inspecting untrusted response content.
+ */
+type ResponseVerificationFailure = 'signature_missing' | 'signature_malformed' | 'signature_invalid' | 'content_digest_mismatch' | 'covered_components_mismatch' | 'unknown_key' | 'key_rejected' | 'algorithm_not_supported' | 'label_unexpected' | 'created_out_of_window';
+
+/**
+ * Thrown when a response cannot be verified, so its content cannot be used.
+ *
+ * @remarks This is an exception rather than a flag on a result because callers must not accidentally act on an
+ * unverified answer.
+ */
+declare class UnverifiableResponseError extends AnisPartnersError {
+    /** The contract reason for refusing the response, without requiring callers to parse message text. */
+    readonly failure: ResponseVerificationFailure;
+    /** Creates a response refusal while keeping its body, signature, base, and key material out of the message. */
+    constructor(failure: ResponseVerificationFailure, detail: string);
+}
+
+/**
+ * An exact currency amount stored as thousandths instead of floating-point units.
+ *
+ * @remarks The contract sends amounts as decimal strings because a floating-point round trip can change the total
+ * checked against unit price multiplied by quantity. Integer thousandths keep that comparison exact.
+ */
+declare class Money {
+    #private;
+    /** ISO currency code associated with this amount. */
+    readonly currency: string;
+    /** Instant at which the amount was computed, when the wire provides one. */
+    readonly asOf?: Date | undefined;
+    private constructor();
+    static [Symbol.hasInstance](value: unknown): boolean;
+    /**
+     * Builds an amount from its decimal wire spelling.
+     *
+     * @remarks A number has already passed through floating-point arithmetic, so accepting one could make an order
+     * total differ from the exact unit price the API checks.
+     */
+    static of(amount: string, currency: string, asOf?: Date): Money;
+    /** The amount rendered with exactly three decimal places so Anis receives the contract's decimal-string form. */
+    get amount(): string;
+    /**
+     * Multiplies by a whole quantity without losing fractional currency units.
+     *
+     * @remarks The source instant describes the unit quote, not the computed order total, so it is cleared on the result.
+     */
+    multiply(quantity: number): Money;
+    /** Uses the familiar decimal and currency spelling when a balance is interpolated into application text. */
+    toString(): string;
+    [inspect.custom](): string;
+    /** Converts to the contract object while retaining its decimal-string amount. */
+    toJSON(): {
+        amount: string;
+        currency: string;
+        asOf?: string;
+    };
+}
+
+/**
+ * A wallet this application may act on after current access and owner rules are applied.
+ *
+ * @remarks The API has already intersected the application's grants with live owner and subscription eligibility;
+ * absent subscription and capability fields are not independent permissions for partners to infer.
+ */
+interface Wallet {
+    /** Wallet identity used by calls on this wallet. */
+    id: string;
+    /** Display name when the owner supplied one. */
+    name?: string;
+    /** Currency code used by its balances and orders. */
+    currency?: string;
+    /** Reserved-adjusted balance and the instant at which it was computed. */
+    balance: Money;
+}
+/**
+ * The application's identity and the scopes its current policy grants.
+ *
+ * @remarks Names and environment are omitted because deployments are isolated copies; exposing a single-valued
+ * environment would invite branching that cannot change the API surface.
+ */
+interface PartnerProfile {
+    /** The Partner identity; names are intentionally not part of this surface. */
+    partner?: PartnerIdentity;
+    /** This application and its effective permissions. */
+    application?: ApplicationIdentity;
+    /** The owner account behind the wallets, when exposed by the surface. */
+    ownerAccount?: OwnerAccount;
+    /** Documentation version this deployment is aligned with. */
+    documentationVersion?: string;
+}
+/** Partner identity, by canonical UUID. */
+interface PartnerIdentity {
+    /** Partner UUID in lower-case hyphenated form. */
+    id: string;
+}
+/**
+ * Application identity and its effective scopes.
+ *
+ * @remarks The application id remains stable while signing keys rotate, and scopes should be read from each response
+ * because policy can change between calls.
+ */
+interface ApplicationIdentity {
+    /** Stable application identity; keys can rotate beneath it. */
+    id: string;
+    /** Scopes in force for calls made now; policy can change between calls. */
+    scopes: readonly string[];
+}
+/** Owner account identity behind the wallets. */
+interface OwnerAccount {
+    /** Owner account UUID in lower-case hyphenated form. */
+    id: string;
+    /** Display name when the owner supplied one. */
+    displayName?: string;
+}
+
+/** Owner-supplied Arabic and English text; either translation can be absent. */
+interface LocalizedText {
+    /** Arabic text when supplied. */
+    ar?: string;
+    /** English text when supplied. */
+    en?: string;
+}
+/** Category source. Unknown wire values remain readable if Anis adds a category kind. */
+type CatalogueCategoryType = 'unknown' | 'local' | 'international';
+/** A published catalogue category. */
+interface CatalogueCategory {
+    /** Category UUID in canonical lower-case form. */
+    id: string;
+    /** Display name, which the owner may provide in either language. */
+    name?: LocalizedText;
+    /** Description, which the owner may provide in either language. */
+    description?: LocalizedText;
+    /** Logo URL when present. */
+    logo?: string;
+    /** Local, international, or unknown when the SDK has not seen a new value. */
+    type: CatalogueCategoryType;
+    /** Whether stock is live under the current owner rules. */
+    inStock: boolean;
+    /** Position chosen by the owner. */
+    displayOrder: number;
+}
+/** A published catalogue subcategory, including buyer-facing terms where present. */
+interface CatalogueSubcategory {
+    /** Subcategory UUID. */
+    id: string;
+    /** Parent category UUID. */
+    categoryId: string;
+    /** Display name, if supplied. */
+    name?: LocalizedText;
+    /** Description, if supplied. */
+    description?: LocalizedText;
+    /** Logo URL when present. */
+    logo?: string;
+    /** Whether the owner marked this subcategory as a best seller. */
+    isBestSelling: boolean;
+    /** Position chosen by the owner. */
+    displayOrder: number;
+    /** Whether it is currently available. */
+    available: boolean;
+    /** Buyer-facing terms to show before purchase; absent when the owner supplied none. */
+    disclaimer?: LocalizedText;
+}
+/** A purchasable card and the price this wallet pays for it. */
+interface CatalogueCard {
+    /** Card UUID used in an order. */
+    id: string;
+    /** Parent subcategory UUID. */
+    subcategoryId: string;
+    /** Display name, if supplied. */
+    name?: LocalizedText;
+    /** Printed face value, when the card has one. */
+    faceValue?: string;
+    /** The current unit price to return as expectedUnitPrice; absent when this wallet cannot buy it. */
+    unitPrice?: Money;
+    /** Business price for comparison and display; an order at a different value may be refused. */
+    businessPrice?: Money;
+    /** Retail price for display, present only above business price. */
+    personalPrice?: Money;
+    /** Whether a special offer applies. */
+    hasSpecialOffer: boolean;
+    /** Display-only offer price when a special offer applies. */
+    specialOfferPrice?: Money;
+    /** Whether the card is live under current owner rules. */
+    available: boolean;
+    /** Lowest quantity accepted in one order, when constrained. */
+    minimumQuantity?: number;
+    /** Highest quantity accepted in one order, when constrained. */
+    maximumQuantity?: number;
+}
+/** One cursor-paged result. Pass nextCursor to continue until it is absent. */
+interface Page<T> {
+    /** Values on this page. */
+    items: readonly T[];
+    /** Cursor for the next page, absent when the list is exhausted. */
+    nextCursor?: string;
+}
+
+/** A sold card as a masked projection; plaintext is never present here. */
+interface MaskedCard {
+    /** Sold-card UUID used by a single-card reveal. */
+    id: string;
+    /** Order that produced this card, when the API exposes it. */
+    orderOperationId?: string;
+    /** Owner invoice needed for invoice-level reveal. */
+    invoiceId?: string;
+    /** Catalogue card summary. */
+    card?: MaskedCardProduct;
+    /** Masked serial for identification without disclosing the credential. */
+    serialNumberMasked?: string;
+    /** Whether Anis currently permits the credential to be revealed. */
+    credentialAvailable: boolean;
+    /** Purchase instant, when supplied. */
+    purchasedAt?: Date;
+    /** Amount originally charged per card, including after a refund. */
+    unitPrice?: Money;
+    /** Last calendar day the card can be used. */
+    expiryDate?: string;
+    /** Number printed on the owner invoice. */
+    invoiceNumber?: number;
+    /** Printed face value when supplied. */
+    faceValue?: string;
+    /** Catalogue subcategory summary. */
+    subcategory?: MaskedCardSubcategory;
+}
+/** A catalogue subcategory summary attached to a sold card. */
+interface MaskedCardSubcategory {
+    /** Subcategory UUID. */
+    id: string;
+    /** Localized name when supplied. */
+    name?: LocalizedText;
+}
+/** A catalogue product summary attached to a sold card or revealed credential. */
+interface MaskedCardProduct {
+    /** Card UUID. */
+    id: string;
+    /** Localized name when supplied. */
+    name?: LocalizedText;
+}
+/**
+ * Credential plaintext returned only by a protected reveal or first order completion.
+ *
+ * @remarks This is the only public model that carries a voucher or serial. Redacting its string form prevents a
+ * careless log interpolation from disclosing credentials.
+ */
+interface RevealedCredential {
+    /** Sold-card UUID this credential belongs to. */
+    soldCardId: string;
+    /** Serial number; keep it out of logs and telemetry. */
+    serialNumber?: string;
+    /** Voucher code; keep it out of logs and telemetry. */
+    voucher?: string;
+    /** Reveal instant when supplied. */
+    revealedAt?: Date;
+    /** Last calendar day the card can be used. */
+    expiryDate?: string;
+    /** Invoice UUID, present on reveal routes. */
+    invoiceId?: string;
+    /** Product summary, present on reveal routes. */
+    card?: MaskedCardProduct;
+    /** Purchase instant, present on reveal routes. */
+    purchasedAt?: Date;
+    /** Redacted representation for accidental string interpolation. */
+    toString(): string;
+    /** Redacted representation for Node's recursive native inspection. */
+    [inspect.custom](): string;
+}
+/** All credentials released for one invoice, or none when the invoice cannot be revealed. */
+interface RevealedCredentialCollection {
+    /** Credentials on this invoice, capped by the public contract. */
+    items: readonly RevealedCredential[];
+}
+
+/**
+ * Order lifecycle state. Unknown future values stay readable as unknown.
+ *
+ * @remarks The parser maps this wire enum explicitly because serializer defaults differ between runtimes. Order
+ * outcomes still depend on the response and replay marker, never on a future status string alone.
+ */
+type OrderStatus = 'unknown' | 'processing' | 'recoveryExhausted' | 'completed' | 'failed';
+/**
+ * What a partner wants to buy. Prices remain exact decimal strings through Money serialization.
+ *
+ * @remarks The gateway rejects unknown request members and compares the total to exact unit-price multiplication;
+ * floating-point arithmetic can therefore turn an apparently valid order into a refusal.
+ */
+interface CreateOrderRequest {
+    /** Catalogue card being purchased. */
+    cardId: string;
+    /** Number of cards, within the live catalogue limits. */
+    quantity: number;
+    /** Price read from the catalogue, echoed to detect price changes. */
+    expectedUnitPrice: Money;
+    /** Exact expected unit price multiplied by quantity. */
+    expectedTotal: Money;
+    /** Partner's own reference, when useful for reconciliation. */
+    externalReference?: string | undefined;
+    /** Explicit consent to use an allowed owner debt balance. */
+    useAllowedDebt?: boolean | undefined;
+}
+/**
+ * An order projection returned by create, resume, or lookup.
+ *
+ * @remarks Credentials appear only on the first completion answer. A replay or lookup is state-only, so use the typed
+ * order result for a compile-time distinction before handling credentials.
+ */
+interface Order {
+    /** Same UUID the caller sent as Idempotency-Key. */
+    operationId: string;
+    /** Current owner-reported order state. */
+    status: OrderStatus;
+    /** Owner invoice UUID once one exists. */
+    invoiceId?: string;
+    /** Wallet UUID the order used. */
+    walletId?: string;
+    /** Catalogue card UUID. */
+    cardId?: string;
+    /** Number of cards. */
+    quantity?: number;
+    /** Total amount charged. */
+    total?: Money;
+    /** Credentials, only on the first response that reports completion. */
+    soldCards?: readonly RevealedCredential[];
+    /** Completion instant. */
+    completedAt?: Date;
+    /** Partner's reference from the create request. */
+    externalReference?: string;
+    /** Recorded refusal code when a lookup reports a failed order. */
+    failureCode?: string;
+    /** Whether the completed order's credentials were withheld; absent means the API did not state it. */
+    codesWithheld?: boolean;
+}
+
+/**
+ * Result of creating or resuming an order; callers must handle all five possible outcomes.
+ *
+ * @remarks Credentials are present only on completion. Keeping the outcomes separate makes that one-time release
+ * rule visible to callers and prevents a missed nullable-field check from losing a purchase.
+ */
+type OrderResult = OrderCompleted | OrderProcessing | OrderReplayed | OrderNotPlaced | OrderOutcomeUnknown;
+/** The order completed and this response carries its one-time credentials. */
+interface OrderCompleted {
+    /** Discriminator for a first completion, including a recovered completion. */
+    kind: 'completed';
+    /** Caller-owned id that ties the completed response to the idempotency key. */
+    operationId: string;
+    /** Order state recorded by Anis. */
+    order: Order;
+    /** Credentials released by this first completion response. */
+    credentials: readonly RevealedCredential[];
+    /** True when the order completed but no credentials could be released. */
+    codesWithheld: boolean;
+}
+/** Anis accepted the order but has not recorded an outcome. */
+interface OrderProcessing {
+    /** Discriminator for an accepted order still processing. */
+    kind: 'processing';
+    /** Caller-owned id to reuse when resuming; a new id could place the cards twice. */
+    operationId: string;
+    /** Current order projection. */
+    order: Order;
+    /** Suggested wait before resuming the same operation id. */
+    suggestedDelayMs: number;
+    /** Location supplied by Anis, when present. */
+    location?: string;
+}
+/** This operation id already received a terminal answer. */
+interface OrderReplayed {
+    /** Discriminator for an already delivered result. */
+    kind: 'replayed';
+    /** Caller-owned id whose terminal answer Anis is returning again. */
+    operationId: string;
+    /** Recorded order state; credentials are not repeated on a replay. */
+    order: Order;
+}
+/** Anis made a final decision that nothing was placed or charged. */
+interface OrderNotPlaced {
+    /** Discriminator for a closed order refusal. */
+    kind: 'notPlaced';
+    /** Caller-owned id for the closed attempt. */
+    operationId: string;
+    /** Typed refusal with the signed problem and response metadata. */
+    refusal: AnisApiError;
+}
+/** The call ended before the client could establish whether the order completed. */
+interface OrderOutcomeUnknown {
+    /** Discriminator for an unresolved order. */
+    kind: 'unknown';
+    /** Caller-owned operation id to reuse when resuming. */
+    operationId: string;
+    /** Suggested delay before resuming the same operation id. */
+    suggestedDelayMs: number;
+    /** Failure or discarded answer that left the order outcome unresolved. */
+    cause: unknown;
+}
+
+/** Client settings that select one issued authority and bound signing, caching, and request time. */
+interface ClientOptions {
+    /** Issued Anis authority; the host is the only environment selector. */
+    authority: string | URL;
+    /** Signature lifetime in seconds. Capped at 60 so a request cannot finish after its answer freshness window. */
+    signatureLifetimeSeconds?: number | undefined;
+    /** Optional Arabic or English presentation preference. */
+    acceptLanguage?: 'ar' | 'en' | undefined;
+    /** Lifetime of the published response signing-key document cache. */
+    signingKeyCacheSeconds?: number | undefined;
+    /** Per-request timeout; an order timeout leaves its outcome unknown. */
+    timeoutMs?: number | undefined;
+    /** Stable host label used for bounded metric dimensions. */
+    name?: string | undefined;
+}
+/** Applies SDK defaults and rejects settings that could place orders whose answers are already stale. */
+interface ValidatedClientOptions {
+    authority: URL;
+    signatureLifetimeSeconds: number;
+    signingKeyCacheSeconds: number;
+    timeoutMs: number;
+    name: string;
+    acceptLanguage?: 'ar' | 'en' | undefined;
+}
+/** Rejects invalid authorities and stale signature lifetimes before a call can become unverifiable or leave an order unresolved. */
+declare function validateClientOptions(options: ClientOptions): ValidatedClientOptions;
+
+/**
+ * The three request shapes accepted by the Partner API.
+ *
+ * @remarks The route selects a frozen shape; a second configurable map could drift from Anis's route rules and turn
+ * a valid signature into an unexplained refusal.
+ */
+type SignatureProfile = 'SafeRead' | 'BodylessNonceMutation' | 'OrderMutation';
+
+/** Creates the single-use nonce that protects a mutation from replay. */
+interface NonceFactory {
+    /** Returns 128 random bits in unpadded base64url; repeated or guessable values are refused as replays. */
+    create(): string;
+}
+
+/** Frozen request settings used by all route groups. */
+interface TransportOptions extends ValidatedClientOptions {
+    /** Route-profile signer. */
+    signer?: RequestSigner;
+    /** Nonce source retained by the transport so every mutation gets a fresh replay guard. */
+    nonceFactory?: NonceFactory;
+    /** Injectable fetch implementation. */
+    fetcher: typeof globalThis.fetch;
+    /** Public response key source. */
+    keySource: SigningKeySource;
+    /** Optional structured diagnostics. */
+    logger?: Partial<PartnerLogger>;
+}
+/** Shared pipeline that signs exact request bytes and verifies a complete response before parsing it. */
+declare class PartnerTransport {
+    private readonly settings;
+    /** Configured bounded telemetry name for this client instance. */
+    get clientName(): string;
+    private readonly requestSigner?;
+    private readonly verifier;
+    private readonly nonceFactory;
+    /** Keeps request signing and response verification together so callers cannot return an unverified answer. */
+    constructor(settings: TransportOptions);
+    /** Sends one API request; response data is not parsed until its signature and digest pass. */
+    send(request: {
+        method: string;
+        route: string;
+        path: string;
+        profile?: SignatureProfile;
+        body?: Uint8Array;
+        operationId?: string;
+        enrollmentToken?: string;
+        signal?: AbortSignal | undefined;
+    }): Promise<{
+        response: Response;
+        body: Uint8Array;
+    }>;
+    /** Sends and parses a verified non-empty JSON success. */
+    json<T>(request: Parameters<PartnerTransport['send']>[0], parse: (value: unknown) => T): Promise<T>;
+    /** Records the closed order outcome without attaching credential data to logs. */
+    reportOrderOutcome(operationId: string, outcome: string, reason?: string): void;
+}
+
+/** Optional caller cancellation applied to one API call. */
+interface CallOptions {
+    /** Stops waiting for this request; for orders, its outcome is still recorded as unknown. */
+    signal?: AbortSignal | undefined;
+}
+/** Optional continuation cursor and cancellation signal for a single page request. */
+interface PageOptions extends CallOptions {
+    /** Cursor returned by the preceding page; omit it to read the first page. */
+    cursor?: string | undefined;
+}
+/** Reads the current profile so callers see policy changes. */
+declare class ProfileOperations {
+    private readonly transport;
+    /** Shares the verified transport so profile reads follow the client's authority and signing policy. */
+    constructor(transport: PartnerTransport);
+    /** Reads identity and effective scopes from the live policy. */
+    get(options?: CallOptions): Promise<PartnerProfile>;
+}
+/** Lists granted wallets and reads one wallet. */
+declare class WalletOperations {
+    private readonly transport;
+    /** Shares the verified transport so wallet reads follow the client's authority and signing policy. */
+    constructor(transport: PartnerTransport);
+    /** Walks wallet pages so callers need not manage continuation cursors. */
+    list(options?: CallOptions): AsyncIterable<Wallet>;
+    /** Reads one page when the caller manages the cursor. */
+    listPage(options?: PageOptions): Promise<Page<Wallet>>;
+    /** Reads one granted wallet by canonical UUID. */
+    get(walletId: string, options?: CallOptions): Promise<Wallet>;
+}
+/** Reads wallet-priced catalogue categories, subcategories, and cards. */
+declare class CatalogueOperations {
+    private readonly transport;
+    /** Shares the verified transport so catalogue reads use the client's price and signing policy. */
+    constructor(transport: PartnerTransport);
+    /** Walks category pages for a wallet. */
+    listCategories(walletId: string, options?: CallOptions): AsyncIterable<CatalogueCategory>;
+    /** Reads one category page. */
+    listCategoriesPage(walletId: string, options?: PageOptions): Promise<Page<CatalogueCategory>>;
+    /** Walks subcategory pages. */
+    listSubcategories(walletId: string, categoryId: string, options?: CallOptions): AsyncIterable<CatalogueSubcategory>;
+    /** Reads one subcategory page. */
+    listSubcategoriesPage(walletId: string, categoryId: string, options?: PageOptions): Promise<Page<CatalogueSubcategory>>;
+    /** Reads one subcategory. */
+    getSubcategory(walletId: string, subcategoryId: string, options?: CallOptions): Promise<CatalogueSubcategory>;
+    /** Walks card pages for the given wallet and subcategory. */
+    listCards(walletId: string, subcategoryId: string, options?: CallOptions): AsyncIterable<CatalogueCard>;
+    /** Reads one catalogue card page. */
+    listCardsPage(walletId: string, subcategoryId: string, options?: PageOptions): Promise<Page<CatalogueCard>>;
+}
+/** Places, resumes, and reads orders under caller-owned operation ids. */
+declare class OrderOperations {
+    private readonly transport;
+    /** Shares the verified transport so order recovery uses the same signer and idempotency rules. */
+    constructor(transport: PartnerTransport);
+    /** Creates an order under an id the caller has persisted, preventing a dropped answer from causing duplicate purchases. */
+    create(walletId: string, operationId: string, order: CreateOrderRequest, options?: CallOptions): Promise<OrderResult>;
+    /** Repeats the same request and operation id to recover an unknown result. */
+    resume(walletId: string, operationId: string, order: CreateOrderRequest, options?: CallOptions): Promise<OrderResult>;
+    /** Reads order state without dispatching a new order or returning credentials. */
+    get(operationId: string, options?: CallOptions): Promise<Order>;
+    private send;
+}
+/** Lists owned cards and reveals credentials only on explicit protected calls. */
+declare class OwnedCardOperations {
+    private readonly transport;
+    /** Shares the verified transport so card reads and reveals keep the client's response checks. */
+    constructor(transport: PartnerTransport);
+    /** Walks owned-card pages. */
+    list(walletId: string, options?: CallOptions): AsyncIterable<MaskedCard>;
+    /** Reads one owned-card page. */
+    listPage(walletId: string, options?: PageOptions): Promise<Page<MaskedCard>>;
+    /** Reads a masked owned card. */
+    get(walletId: string, soldCardId: string, options?: CallOptions): Promise<MaskedCard>;
+    /** Reveals one credential using a signed mutation with no body bytes. */
+    reveal(walletId: string, soldCardId: string, options?: CallOptions): Promise<RevealedCredential>;
+    /** Reveals every credential on an invoice atomically. */
+    revealInvoice(walletId: string, invoiceId: string, options?: CallOptions): Promise<RevealedCredentialCollection>;
+}
+/** Runs the signed, side-effect-free signature admission diagnostic. */
+declare class DiagnosticsOperations {
+    private readonly transport;
+    /** Shares the verified transport so the self-check uses the same request as the partner API. */
+    constructor(transport: PartnerTransport);
+    /** Sends the exact empty JSON object expected by the self-check route. */
+    checkSignature(options?: CallOptions): Promise<SignatureDiagnostic>;
+}
+
+/** Dependencies used to create a signed and verified client. */
+interface AnisPartnersClientCreateOptions {
+    /** Validated authority and request settings. */
+    options: ClientOptions;
+    /** Partner key custody; signatures must be 64-byte P-256 P1363. */
+    signer: RequestSigner;
+    /** Injectable fetch for proxies and in-memory API doubles. */
+    fetch?: typeof globalThis.fetch | undefined;
+    /** Shared key-document cache for short-lived/serverless hosts. */
+    keyCache?: KeyDocumentCache | undefined;
+    /** Optional structured partner log sink. */
+    logger?: Partial<PartnerLogger> | undefined;
+}
+/** Node client whose requests are signed and whose complete responses are verified before parsing. */
+declare class AnisPartnersClient {
+    /** Reads identity and live scopes. */
+    readonly profile: ProfileOperations;
+    /** Lists wallets available to this application. */
+    readonly wallets: WalletOperations;
+    /** Reads wallet-priced catalogue entries. */
+    readonly catalogue: CatalogueOperations;
+    /** Creates and resumes caller-keyed orders. */
+    readonly orders: OrderOperations;
+    /** Reads owned cards and reveals credentials. */
+    readonly ownedCards: OwnedCardOperations;
+    /** Runs the side-effect-free signature check. */
+    readonly diagnostics: DiagnosticsOperations;
+    private constructor();
+    /** Builds the grouped API client and its unsigned public key-document source. */
+    static create(input: AnisPartnersClientCreateOptions): AnisPartnersClient;
+}
+
+/**
+ * Stable OpenTelemetry names for dashboards and host-side instrumentation configuration.
+ *
+ * @remarks These constants keep integrations aligned with the SDK's bounded dimensions so telemetry does not split
+ * into incompatible series after an application upgrade.
+ */
+declare const AnisPartnersTelemetry: {
+    /** Instrumentation scope used for every SDK span and metric. */
+    readonly scope: "@anis-ly/partners";
+    /** Stable low-cardinality attribute names. */
+    readonly attributes: {
+        readonly client: "anis.client";
+        readonly route: "anis.route";
+        readonly method: "http.request.method";
+        readonly statusCode: "http.response.status_code";
+        readonly errorType: "error.type";
+        readonly errorCode: "anis.error.code";
+        readonly operationId: "anis.operation_id";
+        readonly requestId: "anis.request_id";
+    };
+    /** Metric instrument names emitted by the SDK. */
+    readonly instruments: {
+        readonly requestDuration: "anis.partners.request.duration";
+        readonly signatureDuration: "anis.partners.signature.duration";
+        readonly verificationFailures: "anis.partners.response.verification.failures";
+        readonly orderOutcomes: "anis.partners.order.outcomes";
+        readonly signingKeyFetches: "anis.partners.signing_keys.fetches";
+    };
+};
+
+export { AnisApiError, AnisEnrollmentClient, type AnisEnrollmentClientOptions, AnisPartnersClient, type AnisPartnersClientCreateOptions, AnisPartnersError, AnisPartnersTelemetry, type ApplicationIdentity, AuthorizationError, type CallOptions, type CatalogueCard, type CatalogueCategory, type CatalogueCategoryType, CatalogueOperations, type CatalogueSubcategory, type ClientOptions, type CreateOrderRequest, DOMAIN_SEPARATOR, DependencyUnavailableError, DiagnosticsOperations, ERROR_CODES, EnrollmentKeyMismatchError, type EnrollmentKeyRequest, type EnrollmentKeyResult, type EnrollmentProofRequest, EnrollmentRefusedError, type EnrollmentState, type EnrollmentStatus, type ErrorCode, IdempotencyConflictError, InsufficientBalanceError, InvalidCredentialsError, type KeyDocumentCache, KeyedSigner, LimitExceededError, type LocalizedText, MalformedResponseError, type MaskedCard, type MaskedCardProduct, type MaskedCardSubcategory, Money, type Order, type OrderCompleted, type OrderNotPlaced, OrderOperations, type OrderOutcomeUnknown, type OrderProcessing, type OrderRefusalOutcome, type OrderReplayed, type OrderResult, type OrderStatus, OutOfStockError, OwnedCardOperations, type OwnerAccount, type P256Signer, type Page, type PageOptions, type PartnerIdentity, type PartnerJwk, type PartnerLogger, type PartnerProfile, PemP256Signer, PriceChangedError, PrivateKeyError, type Problem, ProfileOperations, RateLimitedError, ReplayDetectedError, type RequestSigner, RequestSigningError, ResourceNotFoundError, type ResponseVerificationFailure, type RevealedCredential, type RevealedCredentialCollection, type SignatureDiagnostic, SigningKeyDocumentUnavailableError, UnverifiableResponseError, type ValidatedClientOptions, ValidationFailedError, type Wallet, WalletOperations, keyThumbprint, proofMessage, proofSignature, safetyCodeFromThumbprint, validateClientOptions };