@majikah/sdk 0.1.0

package/dist/errors/ServiceUnavailableError.d.ts

@@ -0,0 +1,3 @@
+import { APIError } from "./APIError";
+export declare class ServiceUnavailableError extends APIError {
+}

package/dist/errors/ServiceUnavailableError.js

@@ -0,0 +1,4 @@
+import { APIError } from "./APIError";
+// errors/ServiceUnavailableError.ts — 503, e.g. TSA ledger's fail-closed Redis case
+export class ServiceUnavailableError extends APIError {
+}

package/dist/errors/ValidationError.d.ts

@@ -0,0 +1,5 @@
+import { MajikahError } from "./MajikahError";
+export declare class ValidationError extends MajikahError {
+    readonly issues: unknown;
+    constructor(message: string, issues: unknown);
+}

package/dist/errors/ValidationError.js

@@ -0,0 +1,10 @@
+import { MajikahError } from "./MajikahError";
+// errors/ValidationError.ts — client-side, thrown before any network call
+export class ValidationError extends MajikahError {
+    issues;
+    constructor(message, issues) {
+        super(message);
+        this.issues = issues;
+        this.name = "ValidationError";
+    }
+}

package/dist/errors/index.d.ts

@@ -0,0 +1,8 @@
+export { APIError } from "./APIError";
+export { AuthenticationError } from "./AuthenticationError";
+export { MajikahError } from "./MajikahError";
+export { QuotaExhaustedError } from "./QuotaExhaustedError";
+export { RateLimitError } from "./RateLimitError";
+export { ServiceUnavailableError } from "./ServiceUnavailableError";
+export { ValidationError } from "./ValidationError";
+export { mapError } from "./mapError";

package/dist/errors/index.js

@@ -0,0 +1,8 @@
+export { APIError } from "./APIError";
+export { AuthenticationError } from "./AuthenticationError";
+export { MajikahError } from "./MajikahError";
+export { QuotaExhaustedError } from "./QuotaExhaustedError";
+export { RateLimitError } from "./RateLimitError";
+export { ServiceUnavailableError } from "./ServiceUnavailableError";
+export { ValidationError } from "./ValidationError";
+export { mapError } from "./mapError";

package/dist/errors/mapError.d.ts

@@ -0,0 +1,3 @@
+import { APIError } from "./APIError";
+import type { ApiErrorBody } from "../types/common";
+export declare function mapError(status: number, body: ApiErrorBody | undefined, requestId?: string, retryAfterMs?: number): APIError;

package/dist/errors/mapError.js

@@ -0,0 +1,22 @@
+// errors/mapError.ts
+import { APIError } from "./APIError";
+import { AuthenticationError } from "./AuthenticationError";
+import { QuotaExhaustedError } from "./QuotaExhaustedError";
+import { RateLimitError } from "./RateLimitError";
+import { ServiceUnavailableError } from "./ServiceUnavailableError";
+export function mapError(status, body, requestId, retryAfterMs) {
+    const message = body?.error ?? `Request failed with status ${status}`;
+    const code = body?.code ?? "UNKNOWN_ERROR";
+    switch (status) {
+        case 401:
+            return new AuthenticationError(message, status, code, requestId);
+        case 402:
+            return new QuotaExhaustedError(message, status, code, requestId);
+        case 429:
+            return new RateLimitError(message, status, code, retryAfterMs, requestId);
+        case 503:
+            return new ServiceUnavailableError(message, status, code, requestId);
+        default:
+            return new APIError(message, status, code, requestId);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./errors";
+export * from "./types";
+export * from "./services";
+export { MajikahSDKClient } from "./client/MajikahSDKClient";
+export { HttpClient } from "./transport/HttpClient";
+export * from "@majikah/majik-key";
+export * from "@majikah/majik-signature";
+export { MajikUniversalID, type MajikUniversalIDJSON, type MajikID, type PublicProfile, type MajikKeyPublicBundle, type MajikSignerPublicKeys, type ResolvedSignerPublicKeys, MajikIDPublicView, MajikUser, } from "@majikah/majik-universal-id";
+export { createMuidPublicKeyResolver } from "./services/muid/key-resolver";
+export { base64ToBytes, bytesToBase64 } from "./services/shared/encoding";

package/dist/index.js

@@ -0,0 +1,10 @@
+export * from "./errors";
+export * from "./types";
+export * from "./services";
+export { MajikahSDKClient } from "./client/MajikahSDKClient";
+export { HttpClient } from "./transport/HttpClient";
+export * from "@majikah/majik-key";
+export * from "@majikah/majik-signature";
+export { MajikUniversalID, } from "@majikah/majik-universal-id";
+export { createMuidPublicKeyResolver } from "./services/muid/key-resolver";
+export { base64ToBytes, bytesToBase64 } from "./services/shared/encoding";

package/dist/services/index.d.ts

@@ -0,0 +1,4 @@
+export { TSAClient } from "./tsa/TSAClient";
+export { MUIDClient } from "./muid/MUIDClient";
+export { SLinkClient } from "./slink/SLinkClient";
+export { NotaryClient } from "./notary/NotaryClient";

package/dist/services/index.js

@@ -0,0 +1,4 @@
+export { TSAClient } from "./tsa/TSAClient";
+export { MUIDClient } from "./muid/MUIDClient";
+export { SLinkClient } from "./slink/SLinkClient";
+export { NotaryClient } from "./notary/NotaryClient";

package/dist/services/muid/MUIDClient.d.ts

@@ -0,0 +1,95 @@
+import { type EnvelopeInput, type FileLike } from "@majikah/majik-signature";
+import type { HttpClient } from "../../transport/HttpClient";
+import type { MajikIDPublicView, MuidPublicLookupResult, MuidVerifyRequestBody, MuidVerifyResult, VerifyFileDetachedOptions, VerifyFileOptions } from "../../types/muid";
+/**
+ * Client for interacting with the Majik Universal ID (MUID) API.
+ *
+ * Provides direct MUID API operations as well as convenience methods for
+ * verifying signatures embedded in files or stored in detached envelopes.
+ */
+export declare class MUIDClient {
+    private readonly http;
+    /**
+     * Creates a MUID client using the provided HTTP transport.
+     *
+     * @param http HTTP client used to communicate with the Majikah API.
+     */
+    constructor(http: HttpClient);
+    /**
+     * Returns the MUID associated with the current API credentials.
+     *
+     * @returns Public identity information for the authenticated MUID.
+     */
+    me(): Promise<MajikIDPublicView>;
+    /**
+     * Verifies a signature against a MUID.
+     *
+     * @param body Signature verification request containing the signature and
+     * optional MUID identifier.
+     * @returns The result of the MUID verification.
+     * @throws ValidationError When no signature is provided.
+     */
+    verify(body: MuidVerifyRequestBody): Promise<MuidVerifyResult>;
+    /**
+     * Looks up the public MUID associated with an ID or username.
+     *
+     * @param idOrUsername MUID ID or username to look up.
+     * @returns Public MUID information.
+     * @throws ValidationError When the identifier is empty.
+     */
+    lookup(idOrUsername: string): Promise<MuidPublicLookupResult>;
+    /**
+     * Verifies a signature embedded in a file against a MUID.
+     *
+     * The file must already contain a Majik Signature. No signing key is
+     * required because this method only extracts and verifies an existing
+     * signature.
+     *
+     * When the file contains exactly one signature, it is selected
+     * automatically. Multi-signature files require `expectedSignerId` to
+     * explicitly select the signature being verified.
+     *
+     * @param file File containing an embedded Majik Signature.
+     * @param options Optional signer, MUID, and MIME type settings.
+     * @returns The result of the MUID verification.
+     * @throws ValidationError When the file contains no signatures or a
+     * requested signer cannot be resolved.
+     *
+     * @example
+     * ```ts
+     * const result = await majikah.muid.verifyFile(file);
+     * ```
+     *
+     * @example
+     * ```ts
+     * const result = await majikah.muid.verifyFile(file, {
+     *   expectedSignerId: bobFingerprint,
+     *   muid: "bob",
+     * });
+     * ```
+     */
+    verifyFile(file: FileLike, options?: VerifyFileOptions): Promise<MuidVerifyResult>;
+    /**
+     * Verifies a signature contained in a detached envelope against a MUID.
+     *
+     * The envelope supplies the signature and its content hash. The actual
+     * content verification is performed server-side.
+     *
+     * When the envelope contains exactly one signature, it is selected
+     * automatically. Multi-signature envelopes require `expectedSignerId`.
+     *
+     * @param envelope Detached Majik Signature envelope.
+     * @param options Optional signer and MUID settings.
+     * @returns The result of the MUID verification.
+     * @throws ValidationError When the envelope contains no signatures or a
+     * requested signer cannot be resolved.
+     *
+     * @example
+     * ```ts
+     * const result = await majikah.muid.verifyFileDetached(envelope, {
+     *   muid: "alice",
+     * });
+     * ```
+     */
+    verifyFileDetached(envelope: EnvelopeInput, options?: VerifyFileDetachedOptions): Promise<MuidVerifyResult>;
+}

package/dist/services/muid/MUIDClient.js

@@ -0,0 +1,138 @@
+import { MajikSignature, MajikSignatureEnvelope, } from "@majikah/majik-signature";
+import { ValidationError } from "../../errors/ValidationError";
+import { resolveTargetSignature } from "../shared/resolve-signature";
+const NO_SIGNATURE_HINT = "Sign the file first via @majikah/majik-signature before verifying it against a MUID.";
+/**
+ * Client for interacting with the Majik Universal ID (MUID) API.
+ *
+ * Provides direct MUID API operations as well as convenience methods for
+ * verifying signatures embedded in files or stored in detached envelopes.
+ */
+export class MUIDClient {
+    http;
+    /**
+     * Creates a MUID client using the provided HTTP transport.
+     *
+     * @param http HTTP client used to communicate with the Majikah API.
+     */
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Returns the MUID associated with the current API credentials.
+     *
+     * @returns Public identity information for the authenticated MUID.
+     */
+    async me() {
+        return this.http.request("muid", "/me", {
+            method: "GET",
+        });
+    }
+    /**
+     * Verifies a signature against a MUID.
+     *
+     * @param body Signature verification request containing the signature and
+     * optional MUID identifier.
+     * @returns The result of the MUID verification.
+     * @throws ValidationError When no signature is provided.
+     */
+    async verify(body) {
+        if (!body?.signature) {
+            throw new ValidationError("signature is required", body);
+        }
+        return this.http.request("muid", "/verify", {
+            method: "POST",
+            body,
+        });
+    }
+    /**
+     * Looks up the public MUID associated with an ID or username.
+     *
+     * @param idOrUsername MUID ID or username to look up.
+     * @returns Public MUID information.
+     * @throws ValidationError When the identifier is empty.
+     */
+    async lookup(idOrUsername) {
+        if (!idOrUsername) {
+            throw new ValidationError("id or username is required", idOrUsername);
+        }
+        return this.http.request("muid", `/${encodeURIComponent(idOrUsername)}/public`, { method: "GET" });
+    }
+    /**
+     * Verifies a signature embedded in a file against a MUID.
+     *
+     * The file must already contain a Majik Signature. No signing key is
+     * required because this method only extracts and verifies an existing
+     * signature.
+     *
+     * When the file contains exactly one signature, it is selected
+     * automatically. Multi-signature files require `expectedSignerId` to
+     * explicitly select the signature being verified.
+     *
+     * @param file File containing an embedded Majik Signature.
+     * @param options Optional signer, MUID, and MIME type settings.
+     * @returns The result of the MUID verification.
+     * @throws ValidationError When the file contains no signatures or a
+     * requested signer cannot be resolved.
+     *
+     * @example
+     * ```ts
+     * const result = await majikah.muid.verifyFile(file);
+     * ```
+     *
+     * @example
+     * ```ts
+     * const result = await majikah.muid.verifyFile(file, {
+     *   expectedSignerId: bobFingerprint,
+     *   muid: "bob",
+     * });
+     * ```
+     */
+    async verifyFile(file, options) {
+        const signatures = await MajikSignature.extractFrom(file, {
+            mimeType: options?.mimeType,
+        });
+        const target = resolveTargetSignature(signatures, options?.expectedSignerId, {
+            noSignatureHint: NO_SIGNATURE_HINT,
+        });
+        return this.verify({
+            id: options?.muid,
+            signature: target.toJSON(),
+        });
+    }
+    /**
+     * Verifies a signature contained in a detached envelope against a MUID.
+     *
+     * The envelope supplies the signature and its content hash. The actual
+     * content verification is performed server-side.
+     *
+     * When the envelope contains exactly one signature, it is selected
+     * automatically. Multi-signature envelopes require `expectedSignerId`.
+     *
+     * @param envelope Detached Majik Signature envelope.
+     * @param options Optional signer and MUID settings.
+     * @returns The result of the MUID verification.
+     * @throws ValidationError When the envelope contains no signatures or a
+     * requested signer cannot be resolved.
+     *
+     * @example
+     * ```ts
+     * const result = await majikah.muid.verifyFileDetached(envelope, {
+     *   muid: "alice",
+     * });
+     * ```
+     */
+    async verifyFileDetached(envelope, options) {
+        const env = await MajikSignatureEnvelope.from(envelope);
+        const signatures = env.signatures.map((s) => MajikSignature.fromJSON(s));
+        const target = resolveTargetSignature(signatures, options?.expectedSignerId, {
+            noSignatureHint: NO_SIGNATURE_HINT,
+        });
+        return this.verify({
+            id: options?.muid,
+            signature: target.toJSON(),
+        });
+    }
+}
+Object.freeze(MUIDClient);
+Object.freeze(MUIDClient.prototype);

package/dist/services/muid/key-resolver.d.ts

@@ -0,0 +1,24 @@
+import type { MUIDClient } from "./MUIDClient";
+import { PublicKeyResolver } from "../../types/slink";
+/**
+ * Creates a public key resolver backed by MUID lookups.
+ *
+ * The resolver fetches the signer's MUID profile and converts its Base64-
+ * encoded signing keys into the `Uint8Array` format required by
+ * `PublicKeyResolver`.
+ *
+ * @param muidClient MUID client used to resolve public identity information.
+ * @returns A public key resolver suitable for `verifyUrlWithProof()` or
+ * `verifyMatches()`.
+ *
+ * @example
+ * ```ts
+ * const resolvePublicKeys = createMuidPublicKeyResolver(majikah.muid);
+ *
+ * const results = await majikah.slink.verifyUrlWithProof(
+ *   "thezelijah.world",
+ *   resolvePublicKeys,
+ * );
+ * ```
+ */
+export declare function createMuidPublicKeyResolver(muidClient: MUIDClient): PublicKeyResolver;

package/dist/services/muid/key-resolver.js

@@ -0,0 +1,32 @@
+import { base64ToBytes } from "../shared/encoding";
+/**
+ * Creates a public key resolver backed by MUID lookups.
+ *
+ * The resolver fetches the signer's MUID profile and converts its Base64-
+ * encoded signing keys into the `Uint8Array` format required by
+ * `PublicKeyResolver`.
+ *
+ * @param muidClient MUID client used to resolve public identity information.
+ * @returns A public key resolver suitable for `verifyUrlWithProof()` or
+ * `verifyMatches()`.
+ *
+ * @example
+ * ```ts
+ * const resolvePublicKeys = createMuidPublicKeyResolver(majikah.muid);
+ *
+ * const results = await majikah.slink.verifyUrlWithProof(
+ *   "thezelijah.world",
+ *   resolvePublicKeys,
+ * );
+ * ```
+ */
+export function createMuidPublicKeyResolver(muidClient) {
+    return async (muid, signerId) => {
+        const profile = await muidClient.lookup(muid);
+        return {
+            signerId,
+            edPublicKey: base64ToBytes(profile.muid.signing_key.ed_public_key),
+            mlDsaPublicKey: base64ToBytes(profile.muid.signing_key.ml_dsa_public_key),
+        };
+    };
+}

package/dist/services/notary/NotaryClient.d.ts

@@ -0,0 +1,188 @@
+import type { MajikKey } from "@majikah/majik-key";
+import { type FileLike, type MajikChainAnchor } from "@majikah/majik-signature";
+import type { HttpClient } from "../../transport/HttpClient";
+import type { InitiateNotarizationResult, NotaryPaymentResult, PollOptions, SignSealOptions } from "../../types/notary";
+/**
+ * Client for notarizing sealed Majik Signature documents on-chain.
+ *
+ * Notarization uses a two-phase flow:
+ *
+ * 1. A sealed document is identified by its `sealHash` and payment is
+ *    initiated or detected.
+ * 2. After payment is complete, the seal is registered on-chain and the
+ *    resulting anchor is embedded back into the document.
+ *
+ * Lower-level methods such as `payment()`, `register()`, and `status()`
+ * expose the individual API operations, while the higher-level methods
+ * provide complete file-aware workflows.
+ */
+export declare class NotaryClient {
+    private readonly http;
+    /**
+     * Creates a Notary client using the provided HTTP transport.
+     *
+     * @param http HTTP client used to communicate with the Majikah API.
+     */
+    constructor(http: HttpClient);
+    /**
+     * Creates or resumes payment for a sealed document.
+     *
+     * If the seal has already been anchored, the existing chain anchor is
+     * returned and no payment is required.
+     *
+     * If payment has not yet been completed, the response contains checkout
+     * information that can be presented to the user.
+     *
+     * @param sealHash Unique hash identifying the sealed document.
+     * @returns Either an existing chain anchor or payment checkout information.
+     * @throws APIError When payment has already been completed for the seal.
+     */
+    payment(sealHash: string): Promise<NotaryPaymentResult>;
+    /**
+     * Submits a paid seal for on-chain notarization.
+     *
+     * Registration returns immediately. If the anchor is still being confirmed,
+     * use {@link status} or {@link pollUntilTerminal} to track its progress.
+     *
+     * Payment must already be completed for the supplied `sealHash`.
+     *
+     * @param sealHash Unique hash identifying the paid sealed document.
+     * @returns The newly created or existing chain anchor.
+     * @throws APIError When no completed payment exists for the seal hash.
+     */
+    register(sealHash: string): Promise<MajikChainAnchor>;
+    /**
+     * Retrieves the current confirmation status of a notarization anchor.
+     *
+     * @param anchorId Identifier of the chain anchor.
+     * @returns The current chain anchor state.
+     * @throws ValidationError When the anchor ID is empty.
+     */
+    status(anchorId: string): Promise<MajikChainAnchor>;
+    /**
+     * Polls a notarization anchor until it reaches a terminal state.
+     *
+     * Resolves when the anchor becomes `confirmed`, `finalized`, or `failed`.
+     * A failed anchor is returned normally rather than thrown as an exception;
+     * callers should inspect `anchor.status` to determine the outcome.
+     *
+     * @param anchorId Identifier of the chain anchor to monitor.
+     * @param options Polling interval and timeout settings.
+     * @returns The anchor in its terminal state.
+     * @throws MajikahError When the anchor remains pending until the timeout.
+     */
+    pollUntilTerminal(anchorId: string, options?: PollOptions): Promise<MajikChainAnchor>;
+    /**
+     * Starts the payment-aware notarization flow for an already-sealed file.
+     *
+     * This method does not wait for payment or blockchain confirmation.
+     * Its result tells the caller what action is required next:
+     *
+     * - `anchored`: The document was already anchored and the returned blob
+     *   contains the existing anchor.
+     * - `payment_required`: Present the checkout information to the user,
+     *   then call {@link finalizeNotarization} after payment completes.
+     * - `ready_to_finalize`: Payment was previously completed, so
+     *   {@link finalizeNotarization} can be called immediately.
+     *
+     * @param file Sealed file to notarize.
+     * @param options Optional MIME type used when reading and updating the file.
+     * @returns The current state of the notarization flow.
+     * @throws ValidationError When the file is not sealed.
+     *
+     * @example
+     * ```ts
+     * const result = await majikah.notary.initiateNotarization(sealedFile);
+     *
+     * if (result.status === "payment_required") {
+     *   showQrCode(result.checkout.checkout_url);
+     *
+     *   // After the user completes payment:
+     *   const { blob, anchor } =
+     *     await majikah.notary.finalizeNotarization(
+     *       sealedFile,
+     *       result.sealHash,
+     *     );
+     * }
+     * ```
+     */
+    initiateNotarization(file: FileLike, options?: {
+        mimeType?: string;
+    }): Promise<InitiateNotarizationResult>;
+    /**
+     * Completes notarization after payment has been completed.
+     *
+     * Registers the sealed document's `sealHash`, waits for confirmation when
+     * necessary, and embeds the resulting chain anchor back into the file.
+     *
+     * Call this after {@link initiateNotarization} returns either
+     * `payment_required` and the user has paid, or `ready_to_finalize`.
+     *
+     * @param file Sealed file being notarized.
+     * @param sealHash Seal hash returned by {@link initiateNotarization}.
+     * @param options MIME type and polling settings.
+     * @returns The notarized file and its chain anchor.
+     */
+    finalizeNotarization(file: FileLike, sealHash: string, options?: {
+        mimeType?: string;
+        poll?: PollOptions;
+    }): Promise<{
+        blob: Blob;
+        anchor: MajikChainAnchor;
+    }>;
+    /**
+     * Seals an already-signed file and starts the notarization flow.
+     *
+     * Use this when all required signers have already signed the document and
+     * the issuer is ready to seal the signature envelope and begin payment.
+     *
+     * @param file Already-signed file.
+     * @param issuerKey Unlocked MajikKey belonging to the issuer sealing the file.
+     * @param options MIME type and seal timestamp settings.
+     * @returns The current state of the notarization flow.
+     *
+     * @example
+     * ```ts
+     * const result =
+     *   await majikah.notary.sealAndInitiateNotarization(
+     *     signedFile,
+     *     issuerKey,
+     *   );
+     * ```
+     */
+    sealAndInitiateNotarization(file: FileLike, issuerKey: MajikKey, options?: {
+        mimeType?: string;
+        sealTimestamp?: string;
+    }): Promise<InitiateNotarizationResult>;
+    /**
+     * Signs, seals, and starts notarization for a single-signer document.
+     *
+     * This is the complete convenience flow for documents where the supplied
+     * key is the only signer:
+     *
+     * `sign → seal → initiate notarization`
+     *
+     * Sealing makes the envelope immutable to further signatures, so this
+     * method should not be used when additional signers still need to sign.
+     * For multi-signature documents, have all signers sign first and then use
+     * {@link sealAndInitiateNotarization}.
+     *
+     * @param file File to sign and notarize.
+     * @param key Unlocked MajikKey used for both signing and sealing.
+     * @param options Signing, MIME type, validity, and sealing settings.
+     * @returns The current state of the notarization flow.
+     *
+     * @example
+     * ```ts
+     * const result =
+     *   await majikah.notary.signSealAndInitiateNotarization(
+     *     file,
+     *     aliceKey,
+     *     {
+     *       contentType: "application/pdf",
+     *     },
+     *   );
+     * ```
+     */
+    signSealAndInitiateNotarization(file: FileLike, key: MajikKey, options?: SignSealOptions): Promise<InitiateNotarizationResult>;
+}