@morseai/sdk 0.1.0-beta.3

package/dist/index.d.mts

@@ -0,0 +1,510 @@
+type SignalMode = "private" | "shared_wallet";
+type SignalStatus = "active" | "used" | "expired";
+type OnChainNotificationStatus = "pending" | "minted" | "failed" | null;
+interface OnChainNotification {
+    enabled: boolean;
+    network: string;
+    status: OnChainNotificationStatus;
+    txHash: string | null;
+    tokenId: string | null;
+    expiresAt: string | null;
+}
+interface SignalFile {
+    storagePath: string;
+    payloadNonce: string;
+    originalName: string;
+    mimeType: string;
+    sizeBytes: number;
+    sealedDataKey?: string | null;
+    sealedNonce?: string | null;
+    senderEphemeralPublicKey?: string | null;
+    aadHash?: string | null;
+}
+interface CreateSignalOptions {
+    signalId?: string;
+    walletTarget?: string;
+    shareWithRecipient: boolean;
+    mode: SignalMode;
+    hasFile: boolean;
+    hasMessage: boolean;
+    cipherVersion: string;
+    encryptedText?: string;
+    payloadNonce?: string;
+    sealedDataKey?: string;
+    sealedNonce?: string;
+    senderEphemeralPublicKey?: string;
+    aadHash?: string;
+    file?: {
+        storagePath: string;
+        payloadNonce: string;
+        originalName: string;
+        mimeType: string;
+        sizeBytes: number;
+        sealedDataKey?: string;
+        sealedNonce?: string;
+        senderEphemeralPublicKey?: string;
+        aadHash?: string;
+    };
+    onChainNotification?: {
+        enabled: boolean;
+        network: string;
+    };
+    expiresAt?: string;
+    expiresIn?: string;
+}
+interface CreateSignalOptionsEncrypted {
+    signalId?: string;
+    walletTarget?: string;
+    /**
+     * @deprecated shareWithRecipient is automatically determined by mode.
+     * - mode: "shared_wallet" → shareWithRecipient = true
+     * - mode: "private" → shareWithRecipient = false
+     * This field is ignored if provided.
+     */
+    shareWithRecipient?: boolean;
+    mode: SignalMode;
+    message?: string;
+    file?: {
+        data: ArrayBuffer | Uint8Array | Buffer;
+        originalName: string;
+        mimeType: string;
+    };
+    onChainNotification?: {
+        enabled: boolean;
+        network: string;
+    };
+    /**
+     * Specific expiration date and time (ISO 8601 format).
+     * Use this for custom expiration dates.
+     *
+     * Either `expiresAt` OR `expiresIn` must be provided (not both).
+     *
+     * @example "2026-12-31T23:59:59.000Z" - New Year's Eve 2026
+     * @example new Date("2026-12-31").toISOString() - Specific date
+     */
+    expiresAt?: string;
+    /**
+     * Expiration time from now (relative).
+     *
+     * Format: "{number}{unit}" where unit is one of: s (seconds), m (minutes), h (hours), d (days)
+     *
+     * Either `expiresAt` OR `expiresIn` must be provided (not both).
+     *
+     * @example "24h" - 24 hours from now
+     * @example "7d" - 7 days from now
+     * @example "1h" - 1 hour from now
+     * @example "30m" - 30 minutes from now
+     * @example "5s" - 5 seconds from now
+     */
+    expiresIn?: string;
+}
+interface CreateSignalResponse {
+    signalId: string;
+    expiresAt: string;
+}
+interface CreateSignalResponseEncrypted extends CreateSignalResponse {
+    keyBase64: string;
+    shareableLink: string;
+}
+interface OpenSignalResponse {
+    encryptedText: string | null;
+    payloadNonce: string | null;
+    sealedDataKey: string | null;
+    sealedNonce: string | null;
+    senderEphemeralPublicKey: string | null;
+    aadHash: string | null;
+    walletCreator: string | null;
+    walletTarget: string | null;
+    shareWithRecipient: boolean;
+    file: {
+        payloadNonce: string;
+        originalName: string;
+        mimeType: string;
+        sizeBytes: number;
+        sealedDataKey?: string | null;
+        sealedNonce?: string | null;
+        senderEphemeralPublicKey?: string | null;
+        aadHash?: string | null;
+    } | null;
+    expiresAt: string;
+    onChainNotification: OnChainNotification | null;
+    cipherVersion: string;
+}
+interface OpenSignalResponseDecrypted {
+    message: string | null;
+    file: {
+        data: ArrayBuffer;
+        originalName: string;
+        mimeType: string;
+        sizeBytes: number;
+    } | null;
+    expiresAt: string;
+    onChainNotification: OnChainNotification | null;
+    keySource: "derived" | "provided";
+}
+interface SignalListItem {
+    signalId: string;
+    shareWithRecipient: boolean;
+    hasFile: boolean;
+    hasMessage: boolean;
+    createdAt: string;
+    expiresAt: string;
+    used: boolean;
+    status: SignalStatus;
+    file: {
+        originalName: string;
+    } | null;
+}
+interface ListMySignalsResponse {
+    signals: SignalListItem[];
+    count: number;
+}
+interface UploadFileOptions {
+    file: string;
+    originalName: string;
+    mimeType: string;
+}
+interface UploadFileResponse {
+    storagePath: string;
+    sizeBytes: number;
+}
+interface DownloadFileResponse {
+    file: string;
+    originalName: string;
+    mimeType: string;
+    sizeBytes: number;
+}
+interface SignalErrorResponse {
+    status: "error";
+    code: "WALLET_NOT_ALLOWED" | "SIGNAL_EXPIRED" | "SIGNAL_ALREADY_USED" | "SIGNAL_NOT_FOUND" | "VALIDATION_ERROR";
+    message: string;
+}
+interface WalletAuth {
+    address: string;
+    signMessage: (message: string) => Promise<string>;
+}
+interface RateLimitConfig {
+    enabled?: boolean;
+    maxRequests?: number;
+    windowMs?: number;
+}
+interface MorseSDKConfig {
+    apiKey: string;
+    apiVersion?: string;
+    onRequest?: (url: string, options: RequestInit) => void;
+    onResponse?: (url: string, response: Response) => void;
+    onError?: (error: Error) => void;
+    timeout?: number;
+    retries?: number;
+    retryDelay?: number;
+    rateLimit?: RateLimitConfig;
+}
+interface MorseSDKConfigV1 extends MorseSDKConfig {
+    apiVersion?: "v1";
+}
+
+interface MorseContract {
+    createSignal(wallet: WalletAuth, options: CreateSignalOptions): Promise<CreateSignalResponse>;
+    openSignal(wallet: WalletAuth, signalId: string): Promise<OpenSignalResponse>;
+    listMySignals(wallet: WalletAuth): Promise<ListMySignalsResponse>;
+    uploadFile(wallet: WalletAuth, options: UploadFileOptions): Promise<UploadFileResponse>;
+    downloadFile(wallet: WalletAuth, signalId: string): Promise<DownloadFileResponse>;
+    burnSignal(wallet: WalletAuth, signalId: string): Promise<{
+        success: boolean;
+    }>;
+}
+
+interface MorseSDKCallbacks {
+    onRequest?: (url: string, options: RequestInit) => void;
+    onResponse?: (url: string, response: Response) => void;
+    onError?: (error: Error) => void;
+}
+declare class MorseSDK implements MorseContract {
+    private contract;
+    private apiVersion;
+    private config;
+    constructor(config: MorseSDKConfig);
+    getConfig(): Readonly<MorseSDKConfig>;
+    getApiVersion(): string;
+    getContract(): MorseContract;
+    createSignal(wallet: WalletAuth, options: CreateSignalOptions): Promise<CreateSignalResponse>;
+    openSignal(wallet: WalletAuth, signalId: string): Promise<OpenSignalResponse>;
+    listMySignals(wallet: WalletAuth): Promise<ListMySignalsResponse>;
+    uploadFile(wallet: WalletAuth, options: UploadFileOptions): Promise<UploadFileResponse>;
+    downloadFile(wallet: WalletAuth, signalId: string): Promise<DownloadFileResponse>;
+    burnSignal(wallet: WalletAuth, signalId: string): Promise<{
+        success: boolean;
+    }>;
+    createSignalEncrypted(wallet: WalletAuth, options: CreateSignalOptionsEncrypted): Promise<CreateSignalResponseEncrypted>;
+    openSignalDecrypted(wallet: WalletAuth, signalId: string, keyBase64?: string): Promise<OpenSignalResponseDecrypted>;
+    uploadFileEncrypted(wallet: WalletAuth, fileData: ArrayBuffer | Uint8Array | Buffer, originalName: string, mimeType: string, key: CryptoKey): Promise<UploadFileResponse>;
+    downloadFileDecrypted(wallet: WalletAuth, signalId: string, keyBase64: string): Promise<{
+        data: ArrayBuffer;
+        originalName: string;
+        mimeType: string;
+        sizeBytes: number;
+    }>;
+}
+
+interface MorseContractV1 extends MorseContract {
+    readonly version: "v1";
+    createSignal(wallet: WalletAuth, options: CreateSignalOptions): Promise<CreateSignalResponse>;
+    createSignalEncrypted(wallet: WalletAuth, options: CreateSignalOptionsEncrypted): Promise<CreateSignalResponseEncrypted>;
+    openSignal(wallet: WalletAuth, signalId: string): Promise<OpenSignalResponse>;
+    openSignalDecrypted(wallet: WalletAuth, signalId: string, keyBase64?: string): Promise<OpenSignalResponseDecrypted>;
+    listMySignals(wallet: WalletAuth): Promise<ListMySignalsResponse>;
+    uploadFile(wallet: WalletAuth, options: UploadFileOptions): Promise<UploadFileResponse>;
+    uploadFileEncrypted(wallet: WalletAuth, fileData: ArrayBuffer | Uint8Array | Buffer, originalName: string, mimeType: string, key: CryptoKey): Promise<UploadFileResponse>;
+    downloadFile(wallet: WalletAuth, signalId: string): Promise<DownloadFileResponse>;
+    downloadFileDecrypted(wallet: WalletAuth, signalId: string, keyBase64: string): Promise<{
+        data: ArrayBuffer;
+        originalName: string;
+        mimeType: string;
+        sizeBytes: number;
+    }>;
+    burnSignal(wallet: WalletAuth, signalId: string): Promise<{
+        success: boolean;
+    }>;
+}
+
+declare class MorseSDKV1 implements MorseContractV1 {
+    readonly version: "v1";
+    private config;
+    private timeout;
+    private retries;
+    private retryDelay;
+    private rateLimiter;
+    constructor(config: MorseSDKConfig);
+    private base64ToUint8Array;
+    private arrayBufferToBase64;
+    private sanitizeRequestOptions;
+    private getApiUrl;
+    private createAuthMessage;
+    private signMessage;
+    private makeRequest;
+    createSignal(wallet: WalletAuth, options: CreateSignalOptions): Promise<CreateSignalResponse>;
+    openSignal(wallet: WalletAuth, signalId: string): Promise<OpenSignalResponse>;
+    openSignalDecrypted(wallet: WalletAuth, signalId: string, keyBase64?: string): Promise<OpenSignalResponseDecrypted>;
+    listMySignals(wallet: WalletAuth): Promise<ListMySignalsResponse>;
+    uploadFile(wallet: WalletAuth, options: UploadFileOptions): Promise<UploadFileResponse>;
+    downloadFile(wallet: WalletAuth, signalId: string): Promise<DownloadFileResponse>;
+    downloadFileDecrypted(wallet: WalletAuth, signalId: string, keyBase64: string): Promise<{
+        data: ArrayBuffer;
+        originalName: string;
+        mimeType: string;
+        sizeBytes: number;
+    }>;
+    createSignalEncrypted(wallet: WalletAuth, options: CreateSignalOptionsEncrypted): Promise<CreateSignalResponseEncrypted>;
+    private createPrivateSignalEncrypted;
+    private createSharedSignalEncrypted;
+    uploadFileEncrypted(wallet: WalletAuth, fileData: ArrayBuffer | Uint8Array | Buffer, originalName: string, mimeType: string, key: CryptoKey): Promise<UploadFileResponse>;
+    burnSignal(wallet: WalletAuth, signalId: string): Promise<{
+        success: boolean;
+    }>;
+}
+
+interface PrivateKeyWalletConfig {
+    privateKey: string;
+}
+interface PreSignedWalletConfig {
+    address: string;
+    signature: string;
+    message: string;
+}
+declare function createWalletFromPrivateKey(config: PrivateKeyWalletConfig): WalletAuth;
+declare function createWalletFromPreSigned(config: PreSignedWalletConfig): WalletAuth;
+declare function createBrowserWallet(ethereum: any, address?: string): Promise<WalletAuth>;
+
+declare class RateLimitError extends Error {
+    readonly retryAfterMs: number;
+    constructor(message: string, retryAfterMs: number);
+}
+
+declare class MorseSDKError extends Error {
+    code?: string | undefined;
+    statusCode?: number | undefined;
+    constructor(message: string, code?: string | undefined, statusCode?: number | undefined);
+}
+declare class SignalNotFoundError extends MorseSDKError {
+    constructor(message?: string);
+}
+declare class SignalExpiredError extends MorseSDKError {
+    constructor(message?: string);
+}
+declare class SignalAlreadyUsedError extends MorseSDKError {
+    constructor(message?: string);
+}
+declare class WalletNotAllowedError extends MorseSDKError {
+    constructor(message?: string);
+}
+declare class ValidationError extends MorseSDKError {
+    constructor(message?: string);
+}
+declare class NetworkError extends MorseSDKError {
+    originalError?: Error | undefined;
+    constructor(message?: string, originalError?: Error | undefined);
+}
+
+type LogLevel = "none" | "error" | "warn" | "info" | "debug";
+declare class Logger {
+    private level;
+    private levels;
+    setLevel(level: LogLevel): void;
+    getLevel(): LogLevel;
+    private shouldLog;
+    error(message: string, ...args: any[]): void;
+    warn(message: string, ...args: any[]): void;
+    info(message: string, ...args: any[]): void;
+    debug(message: string, ...args: any[]): void;
+}
+declare const logger: Logger;
+
+declare function isValidSignalId(signalId: string): boolean;
+declare function isValidWalletAddress(address: string): boolean;
+declare function validateSignalId(signalId: string): void;
+declare function validateWalletAddress(address: string): void;
+declare function formatExpiration(expiresAt: string): string;
+declare function isSignalExpired(expiresAt: string): boolean;
+declare function getTimeUntilExpiration(expiresAt: string): number;
+declare function parseExpiresIn(expiresIn: string): number;
+declare function filterActiveSignals<T extends {
+    status: string;
+    expiresAt: string;
+}>(signals: T[]): T[];
+declare function sortSignalsByDate<T extends {
+    createdAt: string;
+}>(signals: T[], order?: "asc" | "desc"): T[];
+declare function getSignalUrl(baseUrl: string, signalId: string, keyBase64?: string): string;
+declare function extractSignalIdFromUrl(url: string): string | null;
+
+declare function getCipherVersion(): string;
+declare function generateShareableLink(baseUrl: string, signalId: string, keyBase64: string): string;
+
+/**
+ * MORSE SDK - X25519 + XChaCha20-Poly1305 Encryption
+ *
+ * Compatible with morse-frontend's crypto-x25519.ts
+ *
+ * Security Model:
+ * - X25519 for ECDH key exchange
+ * - XChaCha20-Poly1305 for authenticated encryption
+ * - HKDF-SHA-256 for key derivation
+ * - Ephemeral sender keys (forward secrecy)
+ */
+declare const X25519_CIPHER_VERSION = "morse-x25519-xchacha20poly1305-v2";
+/**
+ * Derive deterministic X25519 keypair from wallet signature
+ */
+declare function deriveKeyPairFromWalletSignature(walletAddress: string, domain: string, chainId: number, signMessage: (message: string) => Promise<string>): Promise<{
+    publicKey: Uint8Array;
+    privateKey: Uint8Array;
+}>;
+/**
+ * Key Certificate interface
+ */
+interface MorseKeyCert {
+    walletAddress: string;
+    x25519PublicKey: string;
+    keyId: string;
+    expiresAt: number;
+    issuedAt: number;
+    domain: string;
+    chainId: number;
+    signature: string;
+}
+/**
+ * Create and sign a key certificate
+ */
+declare function createKeyCertificate(walletAddress: string, x25519PublicKey: string, domain: string, chainId: number, expiresAt: number, signTypedData: (domain: any, types: any, value: any) => Promise<string>): Promise<MorseKeyCert>;
+/**
+ * Verify a key certificate signature
+ */
+declare function verifyKeyCertificate(cert: MorseKeyCert): boolean;
+interface CreateSharedSignalResult {
+    cipherVersion: string;
+    encryptedPayload: string;
+    payloadNonce: string;
+    sealedDataKey: string;
+    sealedNonce: string;
+    senderEphemeralPublicKey: string;
+    aadHash: string;
+}
+/**
+ * Create shared signal (sender side)
+ */
+declare function createSharedSignal(payloadBytes: Uint8Array, recipientPubKey: Uint8Array, walletTarget: string, walletCreator: string, expiresAt: number, signalId: string): Promise<CreateSharedSignalResult>;
+/**
+ * Open shared signal (recipient side)
+ */
+declare function openSharedSignal(encryptedPayloadBase64: string, payloadNonceBase64: string, sealedDataKeyBase64: string, sealedNonceBase64: string, senderEphemeralPublicKeyBase64: string, signalId: string, walletTarget: string, walletCreator: string, expiresAt: number, aadHash: string, walletAddress: string, domain: string, chainId: number, signMessage: (message: string) => Promise<string>): Promise<Uint8Array>;
+/**
+ * Generate a random UUID for signal ID
+ */
+declare function generateSignalId(): string;
+
+/**
+ * Wallet Key Registry Service
+ *
+ * Fetches and publishes X25519 public keys from/to the backend registry
+ */
+
+interface GetPublicKeyResponse {
+    walletAddress: string;
+    certificate: MorseKeyCert | null;
+    exists: boolean;
+}
+declare class WalletKeyService {
+    private baseUrl;
+    private apiKey;
+    private apiVersion;
+    constructor(baseUrl: string, apiKey: string, apiVersion?: string);
+    private getApiUrl;
+    getPublicKey(walletAddress: string): Promise<GetPublicKeyResponse>;
+    publishPublicKey(certificate: MorseKeyCert): Promise<void>;
+}
+
+/**
+ * Common expiration time constants for signals
+ *
+ * Use these constants to ensure correct format and get autocomplete support
+ *
+ * @example
+ * ```typescript
+ * await sdk.createSignalEncrypted(wallet, {
+ *   mode: "shared_wallet",
+ *   walletTarget: "0x...",
+ *   message: "...",
+ *   expiresIn: Expiration.ONE_DAY, // "24h"
+ * });
+ * ```
+ */
+declare const Expiration: {
+    /** 5 seconds */
+    readonly FIVE_SECONDS: "5s";
+    /** 30 seconds */
+    readonly THIRTY_SECONDS: "30s";
+    /** 1 minute */
+    readonly ONE_MINUTE: "1m";
+    /** 5 minutes */
+    readonly FIVE_MINUTES: "5m";
+    /** 30 minutes */
+    readonly THIRTY_MINUTES: "30m";
+    /** 1 hour */
+    readonly ONE_HOUR: "1h";
+    /** 6 hours */
+    readonly SIX_HOURS: "6h";
+    /** 12 hours */
+    readonly TWELVE_HOURS: "12h";
+    /** 24 hours (1 day) */
+    readonly ONE_DAY: "24h";
+    /** 7 days (1 week) */
+    readonly ONE_WEEK: "7d";
+    /** 30 days (1 month) */
+    readonly ONE_MONTH: "30d";
+};
+/**
+ * Type for expiration values
+ */
+type ExpirationValue = typeof Expiration[keyof typeof Expiration] | string;
+
+export { type CreateSharedSignalResult, type CreateSignalOptions, type CreateSignalOptionsEncrypted, type CreateSignalResponse, type CreateSignalResponseEncrypted, type DownloadFileResponse, Expiration, type ExpirationValue, type ListMySignalsResponse, type LogLevel, type MorseContract, type MorseContractV1, type MorseKeyCert, MorseSDK, type MorseSDKCallbacks, type MorseSDKConfig, type MorseSDKConfigV1, MorseSDKError, MorseSDKV1, NetworkError, type OnChainNotification, type OnChainNotificationStatus, type OpenSignalResponse, type OpenSignalResponseDecrypted, type PreSignedWalletConfig, type PrivateKeyWalletConfig, type RateLimitConfig, RateLimitError, SignalAlreadyUsedError, type SignalErrorResponse, SignalExpiredError, type SignalFile, type SignalListItem, type SignalMode, SignalNotFoundError, type SignalStatus, type UploadFileOptions, type UploadFileResponse, ValidationError, type WalletAuth, WalletKeyService, WalletNotAllowedError, X25519_CIPHER_VERSION, createBrowserWallet, createKeyCertificate, createSharedSignal, createWalletFromPreSigned, createWalletFromPrivateKey, deriveKeyPairFromWalletSignature, extractSignalIdFromUrl, filterActiveSignals, formatExpiration, generateShareableLink, generateSignalId, getCipherVersion, getSignalUrl, getTimeUntilExpiration, isSignalExpired, isValidSignalId, isValidWalletAddress, logger, openSharedSignal, parseExpiresIn, sortSignalsByDate, validateSignalId, validateWalletAddress, verifyKeyCertificate };