@majikah/sdk 0.1.0

package/dist/types/notary.d.ts

@@ -0,0 +1,243 @@
+import type { ExpectedSigner, MajikChainAnchor } from "@majikah/majik-signature";
+export type { MajikChainAnchor } from "@majikah/majik-signature";
+/**
+ * Configuration options for polling a pending notarization request.
+ *
+ * Polling is used by convenience methods that wait for an asynchronously
+ * completed notarization or payment flow.
+ */
+export interface PollOptions {
+    /**
+     * Time in milliseconds between consecutive status checks.
+     *
+     * A shorter interval detects state changes sooner but results in more
+     * requests to the gateway.
+     *
+     * @default 2000
+     */
+    intervalMs?: number;
+    /**
+     * Maximum time in milliseconds to wait for the operation to complete.
+     *
+     * The default is slightly longer than the gateway's own pending timeout,
+     * allowing the client to observe a confirmation that arrives near the
+     * server-side timeout boundary.
+     *
+     * @default 130000
+     */
+    timeoutMs?: number;
+}
+/**
+ * Additional options used when creating a cryptographic seal for notarization.
+ *
+ * These values are incorporated into the signing/sealing process and may
+ * affect how the resulting signature is validated.
+ */
+export interface SignSealOptions {
+    /**
+     * Content type associated with the payload being sealed.
+     *
+     * This should describe the logical content being notarized and may be
+     * embedded in the generated signature/seal metadata.
+     *
+     * @example "document"
+     */
+    contentType?: string;
+    /**
+     * Timestamp associated with the signature or seal.
+     *
+     * Expected to be an ISO 8601 timestamp when supplied.
+     *
+     * @example "2026-09-15T01:30:00.000Z"
+     */
+    timestamp?: string;
+    /**
+     * MIME type of the content being notarized.
+     *
+     * This is typically derived from the original file and is useful when
+     * consumers need to preserve or validate the content format.
+     *
+     * @example "application/pdf"
+     */
+    mimeType?: string;
+    /**
+     * Optional list of signers that are expected to participate in the seal.
+     *
+     * When provided, the resulting signature can be validated against the
+     * expected signer set.
+     */
+    expectedSigners?: ExpectedSigner[];
+    /**
+     * Timestamp after which the generated signature or seal should no longer
+     * be considered valid.
+     *
+     * Expected to be an ISO 8601 timestamp when supplied.
+     *
+     * @example "2026-12-31T23:59:59.000Z"
+     */
+    validUntil?: string;
+    /**
+     * Timestamp representing when the notarization seal itself was created.
+     *
+     * Expected to be an ISO 8601 timestamp when supplied.
+     *
+     * @example "2026-09-15T01:30:00.000Z"
+     */
+    sealTimestamp?: string;
+}
+/**
+ * Payment checkout information returned by the notarization payment service.
+ *
+ * This payload contains everything required for a client to present the
+ * payment checkout to a user and track its expiration.
+ */
+export interface NotaryPaymentCheckout {
+    /**
+     * Unique payment order identifier assigned by the payment service.
+     *
+     * Use this identifier when referring to the associated payment transaction.
+     */
+    order_id: string;
+    /**
+     * Data URL containing the QR code for checkout.
+     *
+     * The value is formatted as a `data:image/png;base64,...` URL and can be
+     * supplied directly to an HTML `<img src>` attribute.
+     *
+     * @example "data:image/png;base64,..."
+     */
+    checkout_url: string;
+    /**
+     * Payment amount expressed in the smallest unit of the currency.
+     *
+     * For example, `5000` with `currency: "PHP"` represents ₱50.00.
+     */
+    amount_cents: number;
+    /**
+     * ISO 4217 currency code used for the payment.
+     *
+     * @example "PHP"
+     */
+    currency: string;
+    /**
+     * ISO 8601 timestamp indicating when the checkout expires.
+     *
+     * Clients should avoid presenting an expired checkout to users.
+     *
+     * @example "2026-09-15T02:00:00.000Z"
+     */
+    expires_at: string;
+}
+/**
+ * Response returned by `POST /notary/v1/payment`.
+ *
+ * The result is a discriminated union:
+ *
+ * - `already_anchored` means the document has already been notarized and no
+ *   payment is required.
+ * - `checkout_required` means payment must be completed before notarization
+ *   can be finalized.
+ *
+ * The server removes its internal `outcome` discriminant before returning
+ * the response, so the client determines the variant from the response
+ * `status`.
+ */
+export type NotaryPaymentResult = 
+/**
+ * The document is already anchored on the notarization chain.
+ *
+ * No additional payment or notarization step is required.
+ */
+{
+    /** Indicates that the document is already notarized. */
+    status: "already_anchored";
+    /** Existing blockchain/notarization chain anchor. */
+    anchor: MajikChainAnchor;
+}
+/**
+ * Payment is required before the notarization can be finalized.
+ *
+ * Includes the payment checkout information needed to continue the flow.
+ */
+ | ({
+    /** Indicates that the caller must complete the checkout flow. */
+    status: "checkout_required";
+} & NotaryPaymentCheckout);
+/**
+ * Result returned by the two-phase `initiateNotarization()` convenience flow.
+ *
+ * This discriminated union represents the complete set of states that can
+ * occur while preparing a notarization:
+ *
+ * - `anchored`: the document was already notarized and the existing anchor
+ *   is available.
+ * - `payment_required`: payment must be completed before finalization.
+ * - `ready_to_finalize`: payment is complete or not required and the caller
+ *   can proceed with finalization.
+ */
+export type InitiateNotarizationResult = 
+/**
+ * The document is already notarized.
+ *
+ * The returned blob contains the resulting notarization artifact and
+ * `anchor` contains the existing chain anchor.
+ */
+{
+    /** Indicates that notarization has already been completed. */
+    status: "anchored";
+    /** Resulting notarized artifact. */
+    blob: Blob;
+    /** Existing notarization chain anchor. */
+    anchor: MajikChainAnchor;
+}
+/**
+ * Payment is required before notarization can proceed.
+ *
+ * The sealed artifact is returned unchanged so the caller can retain it
+ * while the payment is completed. The same artifact should be supplied to
+ * `finalizeNotarization()` together with `sealHash`.
+ */
+ | {
+    /** Indicates that payment must be completed before finalization. */
+    status: "payment_required";
+    /**
+     * SHA-256-derived seal hash identifying this sealed notarization
+     * payload.
+     *
+     * Pass this value to `finalizeNotarization()` after payment succeeds.
+     */
+    sealHash: string;
+    /**
+     * The sealed artifact associated with `sealHash`.
+     *
+     * This is returned before payment so the caller can retain the exact
+     * sealed file that will later receive the chain anchor.
+     */
+    sealedBlob: Blob;
+    /** Checkout information required to complete payment. */
+    checkout: NotaryPaymentCheckout;
+}
+/**
+ * The notarization request is ready for finalization.
+ *
+ * Payment has already been completed. The returned `sealedBlob` and
+ * `sealHash` can be passed directly to `finalizeNotarization()`.
+ */
+ | {
+    /** Payment has already been completed, so the returned
+sealed artifact can be finalized immediately. */
+    status: "ready_to_finalize";
+    /**
+     * SHA-256-derived seal hash identifying the notarization payload.
+     *
+     * Pass this value to the finalization step.
+     */
+    sealHash: string;
+    /**
+     * The sealed artifact associated with `sealHash`.
+     *
+     * This is returned before payment so the caller can retain the exact
+     * sealed file that will later receive the chain anchor.
+     */
+    sealedBlob: Blob;
+};

package/dist/types/notary.js

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

package/dist/types/slink.d.ts

@@ -0,0 +1,60 @@
+import type { MajikIDPublicView } from "./muid";
+import { type MajikSLinkJSON, type SLinkClaimType, type SLinkVerificationMethod, type SLinkVerificationStatus } from "@majikah/majik-slink";
+import type { MajikSignerPublicKeys, VerificationResult } from "@majikah/majik-signature";
+export type { MajikSLinkJSON } from "@majikah/majik-slink";
+/**
+ * Options used when creating and registering an SLink for a URL.
+ */
+export interface RegisterUrlOptions {
+    /** Custom identifier for the SLink. */
+    id?: string;
+    /** Timestamp to associate with the SLink claim. */
+    timestamp?: Date;
+    /** Initial verification status of the SLink. */
+    status?: SLinkVerificationStatus;
+    /** Type of claim represented by the SLink. */
+    claimType?: SLinkClaimType;
+    /** Method used to verify the SLink claim. */
+    verificationMethod?: SLinkVerificationMethod;
+}
+/**
+ * An SLink search match together with the result of local cryptographic
+ * verification of its signature.
+ */
+export interface VerifiedSLinkMatch {
+    /** Public SLink and MUID data returned by the API. */
+    match: SLinkPublicView;
+    /** Result of locally verifying the SLink signature. */
+    result: VerificationResult;
+}
+/**
+ * Resolves the public signing keys required to verify an SLink signature.
+ *
+ * The resolver receives the MUID and signer ID from the SLink and may resolve
+ * keys from the MUID API, a local registry, or another trusted source.
+ *
+ * @param muid MUID associated with the SLink.
+ * @param signerId Signer ID recorded in the SLink signature.
+ * @returns Public keys required by `MajikSLink.verifySignature()`.
+ */
+export type PublicKeyResolver = (muid: string, signerId: string) => MajikSignerPublicKeys | Promise<MajikSignerPublicKeys>;
+/**
+ * Public view of an SLink together with the public identity of its owner.
+ */
+export interface SLinkPublicView {
+    /** Public SLink data. */
+    slink: MajikSLinkJSON;
+    /** Public MUID information for the SLink owner. */
+    muid: MajikIDPublicView;
+}
+/**
+ * Result returned when searching for SLinks by hash.
+ */
+export interface SLinkSearchResult {
+    /** Hash used to identify matching SLinks. */
+    hash: string;
+    /** SLinks associated with the requested hash. */
+    matches: SLinkPublicView[];
+    /** Number of matching SLinks returned. */
+    count: number;
+}

package/dist/types/slink.js

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

package/dist/types/tsa.d.ts

@@ -0,0 +1,144 @@
+import { EnvelopeInput, ExpectedSigner, MajikSignature, MajikSignatureEnvelope } from "@majikah/majik-signature";
+export type { MajikTSARequest, MajikTimestamp, MajikTSAPayload, } from "@majikah/majik-signature";
+/**
+ * Represents the gateway-side TSA credit quota available to a caller.
+ *
+ * This is an API and billing concern only. The quota ledger tracks
+ * promotional free stamps and purchased credits and is intentionally
+ * not part of the underlying cryptographic library or its signing
+ * primitives.
+ *
+ * Free credits are subject to a daily reset, while paid credits remain
+ * available until consumed or otherwise expired according to the
+ * gateway's billing policy.
+ */
+export interface TSAQuota {
+    /**
+     * Number of free TSA timestamps remaining in the current quota period.
+     *
+     * This value is decremented when a timestamp operation consumes a
+     * free stamp and is replenished when the quota resets.
+     */
+    free_remaining: number;
+    /**
+     * Maximum number of free TSA timestamps granted during each quota period.
+     *
+     * This represents the full free allowance before any stamps are consumed.
+     */
+    free_daily_limit: number;
+    /**
+     * Number of purchased TSA timestamp credits currently available.
+     *
+     * Paid credits are consumed when the request is charged against the
+     * purchased-credit balance rather than the free allowance.
+     */
+    paid_credits: number;
+    /**
+     * ISO 8601 timestamp indicating when the current free quota period resets.
+     *
+     * This field describes the next reset boundary for `free_remaining` and
+     * does not indicate when paid credits expire.
+     */
+    resets_at: string;
+}
+/**
+ * Options for signing a file and embedding a trusted timestamp into it.
+ */
+export interface StampFileOptions {
+    /** MIME type of the source file. */
+    contentType?: string;
+    /** Existing timestamp value to include in the signature flow. */
+    timestamp?: string;
+    /** MIME type used when re-embedding the signed file. */
+    mimeType?: string;
+    /** Signers expected to participate in the resulting signature. */
+    expectedSigners?: ExpectedSigner[];
+    /** Optional validity period for the resulting signature. */
+    validUntil?: string;
+    /** Optional message associated with the signature chain. */
+    message?: string;
+    /** Previously signed file used to continue an existing signature chain. */
+    priorSignedFile?: Blob;
+}
+/**
+ * Options for signing a file and returning its signature envelope separately
+ * instead of embedding the signature back into the file.
+ */
+export interface StampFileDetachedOptions {
+    /** MIME type of the source file. */
+    contentType?: string;
+    /** Existing timestamp value to include in the signature flow. */
+    timestamp?: string;
+    /** MIME type associated with the signed file. */
+    mimeType?: string;
+    /** Signers expected to participate in the resulting signature. */
+    expectedSigners?: ExpectedSigner[];
+    /** Optional validity period for the resulting signature. */
+    validUntil?: string;
+    /** Existing detached envelope to extend or update. */
+    existingEnvelope?: EnvelopeInput;
+}
+/**
+ * Result returned after signing a file and embedding a trusted timestamp.
+ */
+export interface StampResult {
+    /** Final file containing the updated signature and TSA timestamp. */
+    blob: Blob;
+    /** Signature created for the file. */
+    signature: MajikSignature;
+    /** Handler used to process the file format. */
+    handler: string;
+    /** MIME type of the resulting file. */
+    mimeType: string;
+}
+/**
+ * Result returned after signing a file and creating a detached timestamped
+ * signature envelope.
+ */
+export interface StampDetachedResult {
+    /** Original or processed file returned by the signing operation. */
+    blob: Blob;
+    /** Updated detached signature envelope containing the TSA timestamp. */
+    envelope: MajikSignatureEnvelope;
+    /** Signature created for the file. */
+    signature: MajikSignature;
+    /** Serialized `.mjksig` representation of the updated envelope. */
+    mjksig: Blob;
+    /** Handler used to process the file format. */
+    handler: string;
+    /** MIME type of the resulting file. */
+    mimeType: string;
+}
+/**
+ * Options for attaching a trusted timestamp to an existing signature.
+ */
+export interface TimestampExistingOptions {
+    /**
+     * Signer ID whose signature should receive the TSA.
+     *
+     * Required when the file or envelope contains multiple signatures.
+     */
+    expectedSignerId?: string;
+    /** MIME type of the file being processed. */
+    mimeType?: string;
+}
+/**
+ * Result returned after attaching a trusted timestamp to an embedded signature.
+ */
+export interface TimestampExistingResult {
+    /** File containing the updated timestamped signature. */
+    blob: Blob;
+    /** Signature that received the TSA timestamp. */
+    signature: MajikSignature;
+}
+/**
+ * Result returned after attaching a trusted timestamp to a detached signature.
+ */
+export interface TimestampExistingDetachedResult {
+    /** Updated detached signature envelope. */
+    envelope: MajikSignatureEnvelope;
+    /** Signature that received the TSA timestamp. */
+    signature: MajikSignature;
+    /** Serialized `.mjksig` representation of the updated envelope. */
+    mjksig: Blob;
+}

package/dist/types/tsa.js

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

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@majikah/sdk",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "Official TypeScript client SDK for the Majikah ecosystem, providing unified access to Majik Universal ID (MUID) identity verification, Time Stamping Authority (TSA) issuing, cryptographically signed link claims (SLink), and on-chain document notarization flows.",
+  "license": "Apache-2.0",
+  "author": "Majikah Solutions OPC",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Majikah/majikah-sdk.git"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/jedlsf"
+  },
+  "keywords": [
+    "majikah",
+    "sdk",
+    "typescript",
+    "muid",
+    "tsa",
+    "timestamping",
+    "slink",
+    "notary",
+    "notarization",
+    "digital-signatures",
+    "cryptography",
+    "identity-verification",
+    "blockchain-anchor",
+    "majik-signature",
+    "security"
+  ],
+  "homepage": "https://github.com/Majikah/majikah-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/Majikah/majikah-sdk/issues"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "package": "npm run build && npm version patch && git push && git push --tags",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:tsa": "npx vitest test/sdk-tsa.test.ts",
+    "test:slink": "npx vitest test/sdk-slink.test.ts",
+    "test:notary": "npx vitest test/sdk-notary.test.ts",
+    "test:muid": "npx vitest test/sdk-muid.test.ts"
+  },
+  "dependencies": {
+    "@majikah/majik-key": "^0.4.0",
+    "@majikah/majik-signature": "^0.4.1",
+    "@majikah/majik-slink": "^0.2.1",
+    "@majikah/majik-universal-id": "^0.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.5.1",
+    "dotenv": "^17.4.2",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  }
+}