@majikah/sdk 0.1.0

package/dist/transport/HttpClient.js

@@ -0,0 +1,135 @@
+import { RouteResolver } from "./RouteResolver";
+import { mapError } from "../errors/mapError";
+import { MajikahError } from "../errors/MajikahError";
+import { MAJIKAH_CLIENT_DEFAULTS, resolveVersions, } from "../types/common";
+import { retryWithBackoff } from "./retry";
+import { parseRetryAfterMs } from "./retry-after";
+/**
+ * Internal HTTP transport used by the Majikah SDK service clients.
+ *
+ * Handles API URL resolution, authentication headers, request timeouts,
+ * response parsing, error mapping, and retry behavior for retry-safe requests.
+ */
+export class HttpClient {
+    routes;
+    apiKey;
+    timeoutMs;
+    retry;
+    fetchImpl;
+    extraHeaders;
+    /**
+     * Creates an HTTP client from the SDK configuration.
+     *
+     * @param options API client configuration including authentication,
+     * timeout, retry, and transport settings.
+     * @throws MajikahError When no API key is provided.
+     */
+    constructor(options) {
+        if (!options.apiKey) {
+            throw new MajikahError("MajikahSDKClient requires an apiKey");
+        }
+        this.apiKey = options.apiKey;
+        this.timeoutMs = options.timeoutMs ?? MAJIKAH_CLIENT_DEFAULTS.timeoutMs;
+        this.retry = {
+            ...MAJIKAH_CLIENT_DEFAULTS.retry,
+            ...(options.retry ?? {}),
+        };
+        this.fetchImpl = options.fetch ?? fetch;
+        this.extraHeaders = options.headers ?? {};
+        this.routes = new RouteResolver(options.baseUrl ?? MAJIKAH_CLIENT_DEFAULTS.baseUrl, resolveVersions(options.version));
+    }
+    /**
+     * Sends a request to a Majikah API service.
+     *
+     * GET requests are automatically retried according to the configured retry
+     * policy. POST requests are only retried when explicitly marked as
+     * idempotent.
+     *
+     * Successful API responses are unwrapped and return their `data` value
+     * directly. API errors are converted into SDK-specific error types.
+     *
+     * @typeParam T Expected type of the unwrapped response data.
+     * @param group Service group receiving the request.
+     * @param path API path relative to the service route.
+     * @param opts HTTP method, query parameters, body, and retry settings.
+     * @returns The response data returned by the API.
+     * @throws MajikahError When the request fails or times out.
+     * @throws RateLimitError When the API rejects the request due to rate limits.
+     */
+    async request(group, path, opts) {
+        const url = this.buildUrl(group, path, opts.query);
+        const canRetry = opts.method === "GET" || opts.idempotent === true;
+        if (!canRetry) {
+            return this.attempt(url, opts);
+        }
+        return retryWithBackoff(() => this.attempt(url, opts), this.retry);
+    }
+    /**
+     * Builds a fully resolved API URL from a service route and query parameters.
+     *
+     * Undefined query values are omitted from the final URL.
+     *
+     * @param group Service group used to resolve the API route.
+     * @param path API path relative to the resolved service route.
+     * @param query Optional query parameters.
+     * @returns Fully resolved request URL.
+     */
+    buildUrl(group, path, query) {
+        const url = new URL(this.routes.build(group, path));
+        if (query) {
+            for (const [key, value] of Object.entries(query)) {
+                if (value !== undefined) {
+                    url.searchParams.set(key, value);
+                }
+            }
+        }
+        return url;
+    }
+    /**
+     * Executes a single HTTP request without retrying.
+     *
+     * The response envelope is validated and unwrapped before returning the
+     * contained data. HTTP and API errors are converted through `mapError()`.
+     *
+     * @typeParam T Expected type of the unwrapped response data.
+     * @param url Fully resolved request URL.
+     * @param opts Request configuration.
+     * @returns The response data returned by the API.
+     * @throws MajikahError When the request times out or the API returns an error.
+     */
+    async attempt(url, opts) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const res = await this.fetchImpl(url.toString(), {
+                method: opts.method,
+                headers: {
+                    "X-API-KEY": this.apiKey,
+                    ...(opts.body ? { "Content-Type": "application/json" } : {}),
+                    ...this.extraHeaders,
+                },
+                body: opts.body ? JSON.stringify(opts.body) : undefined,
+                signal: controller.signal,
+            });
+            const requestId = res.headers.get("x-request-id") ?? undefined;
+            const json = (await res.json().catch(() => undefined));
+            if (!res.ok || !json || json.success === false) {
+                throw mapError(res.status, json && json.success === false ? json : undefined, requestId, res.status === 429 ? parseRetryAfterMs(res) : undefined);
+            }
+            return json.data;
+        }
+        catch (err) {
+            if (err instanceof DOMException && err.name === "AbortError") {
+                throw new MajikahError(`Request timed out after ${this.timeoutMs}ms`);
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+// Freeze static methods
+Object.freeze(HttpClient);
+// Freeze instance methods
+Object.freeze(HttpClient.prototype);

package/dist/transport/RouteResolver.d.ts

@@ -0,0 +1,54 @@
+import type { ServiceGroup } from "../types/common";
+/**
+ * Resolves logical service routes into fully qualified, versioned API URLs.
+ *
+ * `RouteResolver` centralizes URL construction so individual service clients
+ * do not need to know the gateway's route prefixes or API versioning scheme.
+ *
+ * The resolver:
+ * - maps a {@link ServiceGroup} to its configured route segment;
+ * - applies the configured API version for that service group;
+ * - normalizes the base URL to prevent duplicate path separators; and
+ * - normalizes the route path to ensure it begins with `/`.
+ *
+ * Instances are intentionally treated as immutable after construction.
+ */
+export declare class RouteResolver {
+    private readonly baseUrl;
+    private readonly versions;
+    /**
+     * Creates a route resolver for the configured API gateway.
+     *
+     * @param baseUrl - Base URL of the API gateway, with or without a trailing `/`.
+     * @param versions - API version number for each supported service group.
+     */
+    constructor(baseUrl: string, versions: Record<ServiceGroup, number>);
+    /**
+     * Builds a fully qualified, versioned route for a service.
+     *
+     * The resulting URL has the following structure:
+     *
+     * `BASE_URL/SERVICE_SEGMENT/vVERSION/PATH`
+     *
+     * Both `baseUrl` and `path` are normalized, so callers may provide
+     * either leading or trailing slashes without producing duplicate `/`
+     * separators at the join points.
+     *
+     * @param group - Logical service group whose route segment and API version
+     *                should be used.
+     * @param path - Service-relative route path, with or without a leading `/`.
+     * @returns The fully qualified, versioned API route.
+     *
+     * @example
+     * ```ts
+     * const resolver = new RouteResolver("https://api.example.com/", {
+     *   tsa: 1,
+     *   muid: 1,
+     * });
+     *
+     * resolver.build("tsa", "/timestamp");
+     * // "https://api.example.com/tsa/v1/timestamp"
+     * ```
+     */
+    build(group: ServiceGroup, path: string): string;
+}

package/dist/transport/RouteResolver.js

@@ -0,0 +1,67 @@
+import { SERVICE_ROUTE_SEGMENT } from "../types/common";
+/**
+ * Resolves logical service routes into fully qualified, versioned API URLs.
+ *
+ * `RouteResolver` centralizes URL construction so individual service clients
+ * do not need to know the gateway's route prefixes or API versioning scheme.
+ *
+ * The resolver:
+ * - maps a {@link ServiceGroup} to its configured route segment;
+ * - applies the configured API version for that service group;
+ * - normalizes the base URL to prevent duplicate path separators; and
+ * - normalizes the route path to ensure it begins with `/`.
+ *
+ * Instances are intentionally treated as immutable after construction.
+ */
+export class RouteResolver {
+    baseUrl;
+    versions;
+    /**
+     * Creates a route resolver for the configured API gateway.
+     *
+     * @param baseUrl - Base URL of the API gateway, with or without a trailing `/`.
+     * @param versions - API version number for each supported service group.
+     */
+    constructor(baseUrl, versions) {
+        this.baseUrl = baseUrl;
+        this.versions = versions;
+    }
+    /**
+     * Builds a fully qualified, versioned route for a service.
+     *
+     * The resulting URL has the following structure:
+     *
+     * `BASE_URL/SERVICE_SEGMENT/vVERSION/PATH`
+     *
+     * Both `baseUrl` and `path` are normalized, so callers may provide
+     * either leading or trailing slashes without producing duplicate `/`
+     * separators at the join points.
+     *
+     * @param group - Logical service group whose route segment and API version
+     *                should be used.
+     * @param path - Service-relative route path, with or without a leading `/`.
+     * @returns The fully qualified, versioned API route.
+     *
+     * @example
+     * ```ts
+     * const resolver = new RouteResolver("https://api.example.com/", {
+     *   tsa: 1,
+     *   muid: 1,
+     * });
+     *
+     * resolver.build("tsa", "/timestamp");
+     * // "https://api.example.com/tsa/v1/timestamp"
+     * ```
+     */
+    build(group, path) {
+        const segment = SERVICE_ROUTE_SEGMENT[group];
+        const version = this.versions[group];
+        const cleanBase = this.baseUrl.replace(/\/+$/, "");
+        const cleanPath = path.startsWith("/") ? path : `/${path}`;
+        return `${cleanBase}/${segment}/v${version}${cleanPath}`;
+    }
+}
+// Freeze static methods
+Object.freeze(RouteResolver);
+// Freeze instance methods
+Object.freeze(RouteResolver.prototype);

package/dist/transport/retry-after.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Parses the standard HTTP `Retry-After` header into milliseconds.
+ *
+ * Per RFC 9110 §10.2.3, the header may be either:
+ *   1. delay-seconds — an integer number of seconds, e.g. "120"
+ *   2. HTTP-date — an absolute timestamp, e.g. "Wed, 21 Oct 2026 07:28:00 GMT"
+ *
+ * Our gateway (buildGatewayResponseHeaders) currently only emits form 1,
+ * but a CDN or edge layer in front of it could plausibly inject form 2,
+ * so both are handled here rather than assuming the numeric case always
+ * holds.
+ *
+ * Returns undefined when the header is missing or doesn't parse as
+ * either form — callers treat that as "no server-specified wait,
+ * fall back to our own backoff schedule."
+ */
+export declare function parseRetryAfterMs(res: Response): number | undefined;

package/dist/transport/retry-after.js

@@ -0,0 +1,39 @@
+/**
+ * Parses the standard HTTP `Retry-After` header into milliseconds.
+ *
+ * Per RFC 9110 §10.2.3, the header may be either:
+ *   1. delay-seconds — an integer number of seconds, e.g. "120"
+ *   2. HTTP-date — an absolute timestamp, e.g. "Wed, 21 Oct 2026 07:28:00 GMT"
+ *
+ * Our gateway (buildGatewayResponseHeaders) currently only emits form 1,
+ * but a CDN or edge layer in front of it could plausibly inject form 2,
+ * so both are handled here rather than assuming the numeric case always
+ * holds.
+ *
+ * Returns undefined when the header is missing or doesn't parse as
+ * either form — callers treat that as "no server-specified wait,
+ * fall back to our own backoff schedule."
+ */
+export function parseRetryAfterMs(res) {
+    const header = res.headers.get("retry-after");
+    if (!header)
+        return undefined;
+    const trimmed = header.trim();
+    // Form 1: delay-seconds. Must be a non-negative integer per spec —
+    // reject negative numbers and non-integer garbage like "12.5abc"
+    // that Number() would otherwise coerce leniently.
+    if (/^\d+$/.test(trimmed)) {
+        const seconds = Number(trimmed);
+        return seconds * 1000;
+    }
+    // Form 2: HTTP-date. Date.parse handles RFC 7231 IMF-fixdate format
+    // (and is lenient enough to also accept a few common variants).
+    const dateMs = Date.parse(trimmed);
+    if (Number.isNaN(dateMs))
+        return undefined;
+    const deltaMs = dateMs - Date.now();
+    // A date in the past (clock skew, or server told us to retry
+    // "immediately" via an already-elapsed timestamp) should mean
+    // "no additional wait," not a negative sleep duration.
+    return Math.max(deltaMs, 0);
+}

package/dist/transport/retry.d.ts

@@ -0,0 +1,8 @@
+import type { RetryOptions } from "../types/common";
+/**
+ * Retries an async function with exponential backoff + jitter.
+ * Only retries errors that pass `isRetryable` — caller still decides
+ * (via HttpClient) whether this method should be attempted more than
+ * once at all, e.g. non-idempotent POSTs like tsa.issue never call this.
+ */
+export declare function retryWithBackoff<T>(fn: () => Promise<T>, options: Required<RetryOptions>, onRetry?: (attempt: number, delayMs: number, err: unknown) => void): Promise<T>;

package/dist/transport/retry.js

@@ -0,0 +1,61 @@
+import { APIError } from "../errors/APIError";
+import { RateLimitError } from "../errors/RateLimitError";
+import { MajikahError } from "../errors/MajikahError";
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Whether an error is worth retrying at all.
+ *
+ * - 5xx / ServiceUnavailableError: transient server-side failure, safe to retry.
+ * - RateLimitError (429): retry, but respect Retry-After if the server gave one
+ *   rather than our own backoff schedule (see retryWithBackoff below).
+ * - MajikahError with no APIError subtype (timeout, network failure, JSON
+ *   parse failure before a status code was even assigned): also transient.
+ * - Anything else — 4xx like 400/401/402/404, or a client-side ValidationError
+ *   that never left the machine — is not retryable. Retrying a malformed
+ *   request or a bad API key just wastes attempts and delays surfacing a
+ *   fixable problem.
+ */
+function isRetryable(err) {
+    if (err instanceof RateLimitError)
+        return true;
+    if (err instanceof APIError)
+        return err.status >= 500;
+    if (err instanceof MajikahError)
+        return true; // timeout / network-level failure
+    return false;
+}
+/**
+ * Retries an async function with exponential backoff + jitter.
+ * Only retries errors that pass `isRetryable` — caller still decides
+ * (via HttpClient) whether this method should be attempted more than
+ * once at all, e.g. non-idempotent POSTs like tsa.issue never call this.
+ */
+export async function retryWithBackoff(fn, options, onRetry) {
+    const { maxAttempts, initialDelayMs, jitterFactor, capDelayMs } = options;
+    let attempt = 0;
+    let delay = initialDelayMs;
+    while (attempt < maxAttempts) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            attempt++;
+            if (!isRetryable(err) || attempt >= maxAttempts) {
+                throw err;
+            }
+            // A server-specified Retry-After overrides our own schedule for 429s —
+            // it's the server telling us exactly when it'll accept work again,
+            // more reliable than guessing with backoff math.
+            const waitMs = err instanceof RateLimitError && err.retryAfterMs !== undefined
+                ? err.retryAfterMs
+                : delay;
+            onRetry?.(attempt, waitMs, err);
+            await sleep(waitMs);
+            delay = Math.min(Math.round(delay * (1.5 + Math.random() * jitterFactor)), capDelayMs);
+        }
+    }
+    // Unreachable — loop always returns or throws — but keeps TS satisfied.
+    throw new MajikahError(`Retry loop exited unexpectedly after ${maxAttempts} attempts`);
+}

package/dist/types/common.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Supported service groups exposed by the Majikah API.
+ */
+export type ServiceGroup = "tsa" | "notary" | "slink" | "muid";
+/**
+ * Maps each service group to the URL path segment used by the API.
+ */
+export declare const SERVICE_ROUTE_SEGMENT: Record<ServiceGroup, string>;
+/**
+ * Configuration options for the Majikah API client.
+ */
+export interface MajikahClientOptions {
+    /** API key used to authenticate requests. */
+    apiKey: string;
+    /** Base URL of the Majikah public API. */
+    baseUrl?: string;
+    /**
+     * API version to use for all services, or individual versions per service.
+     *
+     * A numeric value applies to every service unless overridden by a
+     * service-specific version.
+     */
+    version?: number | Partial<Record<ServiceGroup, number>>;
+    /** Maximum time, in milliseconds, allowed for a single request. */
+    timeoutMs?: number;
+    /** Additional HTTP headers sent with every request. */
+    headers?: Record<string, string>;
+    /** Fetch implementation used for HTTP requests. Defaults to the environment's `fetch`. */
+    fetch?: typeof fetch;
+    /** Request retry behavior. */
+    retry?: RetryOptions;
+}
+/**
+ * Controls how failed API requests are retried.
+ */
+export interface RetryOptions {
+    /** Maximum number of request attempts, including the initial request. */
+    maxAttempts?: number;
+    /** Initial delay before the first retry, in milliseconds. */
+    initialDelayMs?: number;
+    /** Randomization factor applied to retry delays to reduce request synchronization. */
+    jitterFactor?: number;
+    /** Maximum retry delay, in milliseconds. */
+    capDelayMs?: number;
+}
+/**
+ * Default configuration used by the Majikah API client when options are omitted.
+ */
+export declare const MAJIKAH_CLIENT_DEFAULTS: {
+    readonly baseUrl: "https://api-public.majikah.solutions";
+    readonly version: 1;
+    readonly timeoutMs: 15000;
+    readonly retry: Required<RetryOptions>;
+};
+/**
+ * Resolves the effective API version for every supported service.
+ *
+ * A single numeric version is used as the default for all services.
+ * Service-specific versions override that default when provided.
+ *
+ * @param version Global API version or per-service version overrides.
+ * @returns A complete version map containing a version for every service.
+ */
+export declare function resolveVersions(version: MajikahClientOptions["version"]): Record<ServiceGroup, number>;
+/**
+ * Standard success response returned by the Majikah API.
+ *
+ * @typeParam T Type of the successful response data.
+ */
+export interface ApiSuccessBody<T> {
+    /** Indicates that the API request completed successfully. */
+    success: true;
+    /** Human-readable description of the operation result. */
+    message: string;
+    /** Data returned by the requested operation. */
+    data: T;
+}
+/**
+ * Standard error response returned by the Majikah API.
+ */
+export interface ApiErrorBody {
+    /** Indicates that the API request failed. */
+    success: false;
+    /** Human-readable description of the error. */
+    error: string;
+    /** Optional machine-readable error code. */
+    code?: string;
+}
+/**
+ * Union of the standard successful and failed Majikah API responses.
+ *
+ * Use the `success` property as the discriminator when handling a response.
+ *
+ * @typeParam T Type of the successful response data.
+ */
+export type ApiResponseBody<T> = ApiSuccessBody<T> | ApiErrorBody;
+/**
+ * Cursor-based pagination result returned by a Majikah API list endpoint.
+ *
+ * The `next_cursor` value is opaque and should be passed back unchanged as
+ * the `cursor` parameter when requesting the next page.
+ *
+ * @typeParam T Type of items returned in the current page.
+ */
+export interface PageResult<T> {
+    /** Items returned for the current page. */
+    items: T[];
+    /**
+     * Opaque cursor for retrieving the next page.
+     *
+     * `null` indicates that there is no next page.
+     */
+    next_cursor: string | null;
+    /** Indicates whether another page of results is available. */
+    has_more: boolean;
+    /** Number of items returned in the current page. */
+    count: number;
+    /** Maximum number of items requested for the current page. */
+    limit: number;
+}
+/**
+ * Parameters used to request a page of cursor-based results.
+ */
+export interface PaginationParams {
+    /**
+     * Opaque cursor returned by the previous page.
+     *
+     * Omit this value to request the first page.
+     */
+    cursor?: string;
+    /** Maximum number of items to return in the page. */
+    limit?: number;
+}

package/dist/types/common.js

@@ -0,0 +1,42 @@
+/**
+ * Maps each service group to the URL path segment used by the API.
+ */
+export const SERVICE_ROUTE_SEGMENT = {
+    tsa: "tsa",
+    notary: "notary",
+    slink: "slink",
+    muid: "muid",
+};
+/**
+ * Default configuration used by the Majikah API client when options are omitted.
+ */
+export const MAJIKAH_CLIENT_DEFAULTS = {
+    baseUrl: "https://api-public.majikah.solutions",
+    version: 1,
+    timeoutMs: 15_000,
+    retry: {
+        maxAttempts: 3,
+        initialDelayMs: 300,
+        jitterFactor: 0.4,
+        capDelayMs: 5_000,
+    },
+};
+/**
+ * Resolves the effective API version for every supported service.
+ *
+ * A single numeric version is used as the default for all services.
+ * Service-specific versions override that default when provided.
+ *
+ * @param version Global API version or per-service version overrides.
+ * @returns A complete version map containing a version for every service.
+ */
+export function resolveVersions(version) {
+    const fallback = typeof version === "number" ? version : MAJIKAH_CLIENT_DEFAULTS.version;
+    const overrides = typeof version === "object" && version !== null ? version : {};
+    return {
+        tsa: overrides.tsa ?? fallback,
+        notary: overrides.notary ?? fallback,
+        slink: overrides.slink ?? fallback,
+        muid: overrides.muid ?? fallback,
+    };
+}

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+export type * from "./tsa";
+export type * from "./muid";
+export type * from "./slink";
+export * from "./common";

package/dist/types/index.js

@@ -0,0 +1 @@
+export * from "./common";

package/dist/types/muid.d.ts

@@ -0,0 +1,80 @@
+export type { MajikID, MajikIDPublicView, MajikKeyPublicBundle, KeyGenerationRecord, } from "@majikah/majik-universal-id";
+export type { MajikSignatureJSON } from "@majikah/majik-signature";
+import type { KeyGenerationRecord, MajikIDPublicView, SignatureTrustLevel } from "@majikah/majik-universal-id";
+import type { MajikSignatureJSON } from "@majikah/majik-signature";
+/**
+ * Options for verifying an embedded file signature against a MUID.
+ */
+export interface VerifyFileOptions {
+    /**
+     * Signer ID to verify when the file contains multiple signatures.
+     *
+     * Required for multi-signature files to explicitly identify the target
+     * signature.
+     */
+    expectedSignerId?: string;
+    /**
+     * MUID to verify the signature against.
+     *
+     * Accepts either a MUID ID or username. When omitted, the API verifies
+     * against the MUID associated with the caller's API key.
+     */
+    muid?: string;
+    /** MIME type of the file being inspected. */
+    mimeType?: string;
+}
+/**
+ * Options for verifying a signature from a detached envelope against a MUID.
+ */
+export interface VerifyFileDetachedOptions {
+    /**
+     * Signer ID to verify when the envelope contains multiple signatures.
+     *
+     * Required for multi-signature envelopes to explicitly identify the target
+     * signature.
+     */
+    expectedSignerId?: string;
+    /**
+     * MUID to verify the signature against.
+     *
+     * Accepts either a MUID ID or username. When omitted, the API verifies
+     * against the MUID associated with the caller's API key.
+     */
+    muid?: string;
+}
+/**
+ * Request/response shapes for /muid/verify — this exact pairing (an
+ * optional id + a signature envelope, returning a trust verdict) only
+ * exists as an API contract. Neither library models "verify this over
+ * the wire against a resolved identity" as a single object.
+ */
+export interface MuidVerifyRequestBody {
+    id?: string;
+    signature: MajikSignatureJSON;
+}
+export interface MuidVerifyResult {
+    valid: boolean;
+    trustLevel?: SignatureTrustLevel;
+    reason?: string;
+    signerId?: string;
+    timestamp?: string;
+}
+/**
+ * Projected subset of KeyGenerationRecord returned by /muid/:id/public.
+ * Built with Pick against the library type instead of hand-typing the
+ * same five fields again — if the library adds/renames a field, this
+ * either still compiles (safe) or breaks loudly at the Pick (safe),
+ * never silently drifts.
+ */
+export type PublicKeyGeneration = Pick<KeyGenerationRecord, "fingerprint" | "bundle_hash" | "status" | "activated_at" | "deactivated_at">;
+export type PublicSLinkSummary = unknown;
+/**
+ * Composition of a public MUID view + its slinks + key history — this
+ * combined shape is purely the /muid/:id/public response contract, not
+ * something either library exposes as a single type.
+ */
+export interface MuidPublicLookupResult {
+    muid: MajikIDPublicView;
+    slinks: PublicSLinkSummary[];
+    key_history: PublicKeyGeneration[];
+}

package/dist/types/muid.js

@@ -0,0 +1 @@
+export {};