@provablehq/sdk 0.11.7 → 0.11.8

package/dist/mainnet/api-auth.d.cts

@@ -0,0 +1,102 @@
+import { TransportFunction } from "./utils/utils.js";
+/**
+ * Interface for the JWT data.
+ *
+ * @property jwt {string} The JWT token string.
+ * @property expiration {number} The expiration time of the JWT token in UNIX timestamp format (milliseconds).
+ */
+export interface JWTData {
+    jwt: string;
+    expiration: number;
+}
+/** Default header carrying a provisioned API key (e.g. edge.provable.com). */
+export declare const DEFAULT_API_KEY_HEADER = "X-API-Key";
+/**
+ * Authentication configuration for Provable API services.
+ *
+ * Two live modes exist, matching the two gateways:
+ * - `jwt` (api.provable.com): the apiKey + consumerId pair mints a short-lived JWT at
+ *   `/jwts/{consumerId}` which is sent as an `Authorization` header and refreshed near expiry.
+ * - `api-key` (edge.provable.com): a provisioned key is sent verbatim on every request in a
+ *   header (default `X-API-Key`). There is no registration, minting, or refresh in this mode;
+ *   a 401 means the key is invalid or revoked and retrying cannot help.
+ * - `none`: requests carry no auth headers.
+ */
+export type ApiAuthConfig = {
+    mode: "jwt";
+    apiKey?: string;
+    consumerId?: string;
+    jwtData?: JWTData;
+} | {
+    mode: "api-key";
+    value: string;
+    header?: string;
+} | {
+    mode: "none";
+};
+/**
+ * Legacy authentication options accepted by {@link AleoNetworkClient} and {@link RecordScanner}
+ * before explicit modes existed. Normalized by {@link normalizeAuthConfig}.
+ */
+export interface LegacyAuthOptions {
+    auth?: ApiAuthConfig;
+    apiKey?: string | {
+        header: string;
+        value: string;
+    };
+    consumerId?: string;
+    jwtData?: JWTData;
+}
+/**
+ * Normalize legacy auth options into an explicit {@link ApiAuthConfig}.
+ *
+ * Rules, preserving the pre-mode behavior of both clients:
+ * - An explicit `auth` wins. Combining it with legacy fields throws — the caller's intent
+ *   is ambiguous and guessing hides misconfiguration.
+ * - A string `apiKey` (with or without `consumerId`) or a bare `jwtData` selects `jwt` mode.
+ * - An `{ header, value }` apiKey selects `api-key` mode with that header. Combining it with
+ *   a `consumerId` throws: keyed auth has no consumer and the pair would silently pick one.
+ * - Nothing configured selects `none`.
+ */
+export declare function normalizeAuthConfig(options: LegacyAuthOptions): ApiAuthConfig;
+/**
+ * ApiAuth resolves the auth headers each request must carry, owning the JWT mint/refresh
+ * lifecycle in `jwt` mode. Share one instance across clients that use the same credentials so
+ * only one minter exists and concurrent refreshes are deduplicated.
+ */
+export declare class ApiAuth {
+    readonly config: ApiAuthConfig;
+    private readonly baseUrl;
+    private readonly transport;
+    private jwtData?;
+    private inFlight?;
+    private warned;
+    private readonly mintHeaders;
+    /**
+     * @param {ApiAuthConfig} config The auth mode and its material.
+     * @param {string} baseUrl API root origin; `/jwts/{consumerId}` lives here in `jwt` mode.
+     * @param {TransportFunction} transport Transport used for the JWT mint request.
+     * @param {Record<string, string>} [mintHeaders] Extra headers on the mint request (e.g. SDK telemetry).
+     */
+    constructor(config: ApiAuthConfig, baseUrl: string, transport?: TransportFunction, mintHeaders?: Record<string, string>);
+    /** The mode this instance authenticates with. */
+    get mode(): ApiAuthConfig["mode"];
+    /** Replace the stored JWT, e.g. one minted elsewhere. Only meaningful in `jwt` mode. */
+    setJwtData(jwtData: JWTData | undefined): void;
+    /** The stored JWT, when one exists. */
+    getJwtData(): JWTData | undefined;
+    /**
+     * The auth headers a request must carry, refreshing the JWT first when it is stale and a
+     * refresh is possible. Returns an empty object in `none` mode or when `jwt` mode lacks
+     * both a usable token and the material to mint one.
+     */
+    headers(): Promise<Record<string, string>>;
+    /**
+     * Refreshes the JWT by making a POST request to /jwts/{consumer_id}.
+     *
+     * @param {string} apiKey The API key to use for the refresh request.
+     * @param {string} consumerId The consumer ID for the JWT endpoint.
+     * @returns {Promise<JWTData>} The new JWT data.
+     */
+    private refreshJwt;
+}

package/dist/mainnet/api-auth.d.ts

@@ -0,0 +1,102 @@
+import { TransportFunction } from "./utils/utils.js";
+/**
+ * Interface for the JWT data.
+ *
+ * @property jwt {string} The JWT token string.
+ * @property expiration {number} The expiration time of the JWT token in UNIX timestamp format (milliseconds).
+ */
+export interface JWTData {
+    jwt: string;
+    expiration: number;
+}
+/** Default header carrying a provisioned API key (e.g. edge.provable.com). */
+export declare const DEFAULT_API_KEY_HEADER = "X-API-Key";
+/**
+ * Authentication configuration for Provable API services.
+ *
+ * Two live modes exist, matching the two gateways:
+ * - `jwt` (api.provable.com): the apiKey + consumerId pair mints a short-lived JWT at
+ *   `/jwts/{consumerId}` which is sent as an `Authorization` header and refreshed near expiry.
+ * - `api-key` (edge.provable.com): a provisioned key is sent verbatim on every request in a
+ *   header (default `X-API-Key`). There is no registration, minting, or refresh in this mode;
+ *   a 401 means the key is invalid or revoked and retrying cannot help.
+ * - `none`: requests carry no auth headers.
+ */
+export type ApiAuthConfig = {
+    mode: "jwt";
+    apiKey?: string;
+    consumerId?: string;
+    jwtData?: JWTData;
+} | {
+    mode: "api-key";
+    value: string;
+    header?: string;
+} | {
+    mode: "none";
+};
+/**
+ * Legacy authentication options accepted by {@link AleoNetworkClient} and {@link RecordScanner}
+ * before explicit modes existed. Normalized by {@link normalizeAuthConfig}.
+ */
+export interface LegacyAuthOptions {
+    auth?: ApiAuthConfig;
+    apiKey?: string | {
+        header: string;
+        value: string;
+    };
+    consumerId?: string;
+    jwtData?: JWTData;
+}
+/**
+ * Normalize legacy auth options into an explicit {@link ApiAuthConfig}.
+ *
+ * Rules, preserving the pre-mode behavior of both clients:
+ * - An explicit `auth` wins. Combining it with legacy fields throws — the caller's intent
+ *   is ambiguous and guessing hides misconfiguration.
+ * - A string `apiKey` (with or without `consumerId`) or a bare `jwtData` selects `jwt` mode.
+ * - An `{ header, value }` apiKey selects `api-key` mode with that header. Combining it with
+ *   a `consumerId` throws: keyed auth has no consumer and the pair would silently pick one.
+ * - Nothing configured selects `none`.
+ */
+export declare function normalizeAuthConfig(options: LegacyAuthOptions): ApiAuthConfig;
+/**
+ * ApiAuth resolves the auth headers each request must carry, owning the JWT mint/refresh
+ * lifecycle in `jwt` mode. Share one instance across clients that use the same credentials so
+ * only one minter exists and concurrent refreshes are deduplicated.
+ */
+export declare class ApiAuth {
+    readonly config: ApiAuthConfig;
+    private readonly baseUrl;
+    private readonly transport;
+    private jwtData?;
+    private inFlight?;
+    private warned;
+    private readonly mintHeaders;
+    /**
+     * @param {ApiAuthConfig} config The auth mode and its material.
+     * @param {string} baseUrl API root origin; `/jwts/{consumerId}` lives here in `jwt` mode.
+     * @param {TransportFunction} transport Transport used for the JWT mint request.
+     * @param {Record<string, string>} [mintHeaders] Extra headers on the mint request (e.g. SDK telemetry).
+     */
+    constructor(config: ApiAuthConfig, baseUrl: string, transport?: TransportFunction, mintHeaders?: Record<string, string>);
+    /** The mode this instance authenticates with. */
+    get mode(): ApiAuthConfig["mode"];
+    /** Replace the stored JWT, e.g. one minted elsewhere. Only meaningful in `jwt` mode. */
+    setJwtData(jwtData: JWTData | undefined): void;
+    /** The stored JWT, when one exists. */
+    getJwtData(): JWTData | undefined;
+    /**
+     * The auth headers a request must carry, refreshing the JWT first when it is stale and a
+     * refresh is possible. Returns an empty object in `none` mode or when `jwt` mode lacks
+     * both a usable token and the material to mint one.
+     */
+    headers(): Promise<Record<string, string>>;
+    /**
+     * Refreshes the JWT by making a POST request to /jwts/{consumer_id}.
+     *
+     * @param {string} apiKey The API key to use for the refresh request.
+     * @param {string} consumerId The consumer ID for the JWT endpoint.
+     * @returns {Promise<JWTData>} The new JWT data.
+     */
+    private refreshJwt;
+}