@proofrails/sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,546 @@
+/**
+ * Common types used across the SDK
+ */
+type Network = 'coston2' | 'flare';
+type ReceiptStatus = 'pending' | 'anchored' | 'failed';
+interface SDKConfig {
+    /** Your ProofRails API key */
+    apiKey?: string;
+    /** Admin token for administrative operations */
+    adminToken?: string;
+    /** Network to use (coston2 or flare) */
+    network?: Network;
+    /** Base URL of the middleware (optional, defaults to production) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Number of retry attempts for failed requests (default: 3) */
+    retries?: number;
+    /** Delay between retries in milliseconds (default: 1000) */
+    retryDelay?: number;
+}
+interface APIResponse<T> {
+    data: T;
+    success: boolean;
+    error?: string;
+}
+interface PaginatedResponse<T> {
+    items: T[];
+    total: number;
+    page: number;
+    limit: number;
+}
+declare class ProofRailsError extends Error {
+    code?: string | undefined;
+    statusCode?: number | undefined;
+    details?: unknown | undefined;
+    constructor(message: string, code?: string | undefined, statusCode?: number | undefined, details?: unknown | undefined);
+}
+
+/**
+ * Core HTTP client for ProofRails API
+ */
+
+interface RateLimitInfo {
+    limit: number;
+    remaining: number;
+    reset: number;
+    resetDate: Date;
+}
+declare class APIClient {
+    private baseUrl;
+    private apiKey?;
+    private adminToken?;
+    private timeout;
+    private retries;
+    private retryDelay;
+    private rateLimitInfo;
+    constructor(config?: SDKConfig);
+    getRateLimitInfo(): RateLimitInfo | null;
+    get<T>(endpoint: string, options?: RequestInit): Promise<T>;
+    post<T>(endpoint: string, body?: unknown, options?: RequestInit): Promise<T>;
+    put<T>(endpoint: string, body?: unknown, options?: RequestInit): Promise<T>;
+    delete<T>(endpoint: string, options?: RequestInit): Promise<T>;
+    private request;
+    private shouldRetry;
+    private retryRequest;
+    private extractRateLimitInfo;
+    setApiKey(apiKey: string): void;
+    setAdminToken(adminToken: string): void;
+    getBaseUrl(): string;
+}
+
+/**
+ * Project and API key related types
+ */
+interface Project {
+    projectId: string;
+    label?: string;
+    createdAt: string;
+    receiptsCount?: number;
+}
+interface APIKey {
+    apiKey: string;
+    projectId: string;
+    label?: string;
+    createdAt: string;
+}
+interface CreateProjectOptions {
+    label?: string;
+}
+interface CreateAPIKeyOptions {
+    projectId: string;
+    label?: string;
+}
+interface WhoAmIResponse {
+    projectId: string;
+    label?: string;
+}
+
+/**
+ * Project and API key management module
+ */
+
+declare class ProjectsModule {
+    private client;
+    constructor(client: APIClient);
+    getInfo(): Promise<WhoAmIResponse>;
+    rotateKey(): Promise<APIKey>;
+    create(options?: CreateProjectOptions): Promise<APIKey>;
+}
+declare class AdminModule {
+    private client;
+    constructor(client: APIClient);
+    createKey(options: CreateAPIKeyOptions): Promise<APIKey>;
+    deleteKey(keyId: string): Promise<void>;
+}
+
+/**
+ * Receipt related types
+ */
+
+interface CreateReceiptOptions {
+    transactionHash: string;
+    chain: Network;
+    amount: string | number;
+    currency: string;
+    sender: string;
+    receiver: string;
+    reference: string;
+    callbackUrl?: string;
+}
+interface Receipt {
+    id: string;
+    status: ReceiptStatus;
+    transactionHash: string;
+    chain: Network;
+    amount: string;
+    currency: string;
+    sender: string;
+    receiver: string;
+    reference: string;
+    createdAt: string;
+    anchoredAt?: string;
+    anchorTx?: string;
+    bundleHash?: string;
+    projectId?: string;
+    onChain?: boolean;
+    valid?: boolean;
+}
+interface ReceiptArtifacts {
+    pain001Url?: string;
+    pain002Url?: string;
+    pain007Url?: string;
+    pain008Url?: string;
+    camt054Url?: string;
+    bundleUrl?: string;
+    manifestUrl?: string;
+}
+interface ListReceiptsOptions {
+    limit?: number;
+    page?: number;
+    status?: ReceiptStatus;
+}
+interface ReceiptUpdate {
+    id: string;
+    status: ReceiptStatus;
+    anchorTx?: string;
+    bundleHash?: string;
+    timestamp: string;
+}
+
+/**
+ * Receipt operations module
+ */
+
+declare class ReceiptsModule {
+    private client;
+    constructor(client: APIClient);
+    create(options: CreateReceiptOptions): Promise<Receipt>;
+    get(receiptId: string): Promise<Receipt>;
+    list(options?: ListReceiptsOptions): Promise<PaginatedResponse<Receipt>>;
+    getArtifacts(receiptId: string): Promise<ReceiptArtifacts>;
+}
+
+/**
+ * Verification related types
+ */
+interface VerificationResult {
+    valid: boolean;
+    bundleHash: string;
+    onChain: boolean;
+    anchorTx?: string;
+    blockNumber?: number;
+    timestamp?: string;
+    signature?: string;
+    details?: Record<string, unknown>;
+}
+interface VerificationProof {
+    receiptId: string;
+    bundleHash: string;
+    anchorTx: string;
+    blockNumber: number;
+    timestamp: string;
+    signature: string;
+    network: string;
+    contractAddress: string;
+}
+
+/**
+ * Verification module
+ */
+
+declare class VerificationModule {
+    private client;
+    constructor(client: APIClient);
+    byReceiptId(receiptId: string): Promise<VerificationResult>;
+    byUrl(bundleUrl: string): Promise<VerificationResult>;
+    byHash(bundleHash: string): Promise<VerificationResult>;
+    getProof(receiptId: string): Promise<VerificationProof>;
+}
+
+/**
+ * ISO 20022 message types
+ */
+type ISOMessageType = 'pain.001' | 'pain.002' | 'pain.007' | 'pain.008' | 'camt.052' | 'camt.053' | 'camt.054';
+interface ISOMessage {
+    type: ISOMessageType;
+    messageId: string;
+    url: string;
+    createdAt: string;
+}
+interface GenerateStatementOptions {
+    dateFrom?: string;
+    dateTo?: string;
+    accountId?: string;
+}
+interface Statement {
+    type: 'camt.052' | 'camt.053';
+    url: string;
+    downloadUrl: string;
+    messageId: string;
+    createdAt: string;
+}
+
+/**
+ * Statements module
+ */
+
+declare class StatementsModule {
+    private client;
+    constructor(client: APIClient);
+    intraday(options?: GenerateStatementOptions): Promise<Statement>;
+    endOfDay(options?: GenerateStatementOptions): Promise<Statement>;
+}
+
+/**
+ * Events module for live updates
+ */
+
+interface EventListener {
+    stop: () => void;
+}
+declare class EventsModule {
+    private client;
+    constructor(client: APIClient);
+    listen(receiptId: string, callback: (update: ReceiptUpdate) => void): EventListener;
+}
+
+/**
+ * Embed module for generating embeddable widgets
+ */
+
+interface EmbedOptions {
+    theme?: 'light' | 'dark';
+    width?: string;
+    height?: string;
+}
+interface WidgetResult {
+    iframeHtml: string;
+    embedUrl: string;
+}
+declare class EmbedModule {
+    private client;
+    constructor(client: APIClient);
+    widget(receiptId: string, options?: EmbedOptions): WidgetResult;
+    fullPage(receiptId: string): string;
+}
+
+/**
+ * Payment template - For simple payments between two parties
+ */
+
+interface PaymentTemplateOptions {
+    /** Payment amount */
+    amount: number;
+    /** Who is sending the payment */
+    from: string;
+    /** Who is receiving the payment */
+    to: string;
+    /** What the payment is for */
+    purpose: string;
+    /** Blockchain transaction hash */
+    transactionHash: string;
+    /** Sender's wallet address (optional, defaults to transaction sender) */
+    senderWallet?: string;
+    /** Receiver's wallet address (optional, defaults to transaction receiver) */
+    receiverWallet?: string;
+    /** Chain/network (optional, auto-detected if not provided) */
+    chain?: 'coston2' | 'flare';
+    /** Currency (optional, auto-detected if not provided) */
+    currency?: string;
+}
+declare function createPaymentReceipt(receiptsModule: ReceiptsModule, options: PaymentTemplateOptions): Promise<Receipt>;
+
+/**
+ * Donation template - For charitable donations
+ */
+
+interface DonationTemplateOptions {
+    /** Donation amount */
+    amount: number;
+    /** Name of the donor */
+    donor: string;
+    /** Name of the organization receiving the donation */
+    organization: string;
+    /** Campaign or cause name */
+    campaign: string;
+    /** Blockchain transaction hash */
+    transactionHash: string;
+    /** Donor's wallet address (optional) */
+    donorWallet?: string;
+    /** Organization's wallet address (optional) */
+    organizationWallet?: string;
+}
+declare function createDonationReceipt(receiptsModule: ReceiptsModule, options: DonationTemplateOptions): Promise<Receipt>;
+
+/**
+ * Escrow template - For escrow releases
+ */
+
+interface EscrowTemplateOptions {
+    /** Amount being released from escrow */
+    amount: number;
+    /** Buyer's name */
+    buyer: string;
+    /** Seller's name */
+    seller: string;
+    /** Escrow identifier */
+    escrowId: string;
+    /** Reason for release */
+    releaseReason: string;
+    /** Blockchain transaction hash */
+    transactionHash: string;
+    /** Buyer's wallet address (optional) */
+    buyerWallet?: string;
+    /** Seller's wallet address (optional) */
+    sellerWallet?: string;
+}
+declare function createEscrowReceipt(receiptsModule: ReceiptsModule, options: EscrowTemplateOptions): Promise<Receipt>;
+
+/**
+ * Grant template - For grant disbursements
+ */
+
+interface GrantTemplateOptions {
+    /** Grant amount */
+    amount: number;
+    /** Name of the grantee (recipient) */
+    grantee: string;
+    /** Name of the grantor (funder) */
+    grantor: string;
+    /** Grant identifier */
+    grantId: string;
+    /** Purpose of the grant */
+    purpose: string;
+    /** Blockchain transaction hash */
+    transactionHash: string;
+    /** Grantor's wallet address (optional) */
+    grantorWallet?: string;
+    /** Grantee's wallet address (optional) */
+    granteeWallet?: string;
+}
+declare function createGrantReceipt(receiptsModule: ReceiptsModule, options: GrantTemplateOptions): Promise<Receipt>;
+
+/**
+ * Refund template - For refunds
+ */
+
+interface RefundTemplateOptions {
+    /** Refund amount */
+    amount: number;
+    /** Original receipt ID being refunded */
+    originalPayment: string;
+    /** Reason for refund */
+    reason: string;
+    /** Customer name */
+    customer: string;
+    /** Blockchain transaction hash */
+    transactionHash: string;
+    /** Business wallet address (optional) */
+    businessWallet?: string;
+    /** Customer wallet address (optional) */
+    customerWallet?: string;
+}
+declare function createRefundReceipt(receiptsModule: ReceiptsModule, options: RefundTemplateOptions): Promise<Receipt>;
+
+/**
+ * Main ProofRails SDK class
+ */
+
+declare class ProofRails {
+    private client;
+    /** Project and API key management */
+    readonly project: ProjectsModule;
+    /** Admin operations (requires admin token) */
+    readonly admin: AdminModule;
+    /** Receipt operations */
+    readonly receipts: ReceiptsModule;
+    /** Verification operations */
+    readonly verify: VerificationModule;
+    /** Statement generation */
+    readonly statements: StatementsModule;
+    /** Live event updates */
+    readonly events: EventsModule;
+    /** Embeddable widgets */
+    readonly embed: EmbedModule;
+    /** Beginner-friendly templates */
+    readonly templates: {
+        payment: (options: PaymentTemplateOptions) => ReturnType<typeof createPaymentReceipt>;
+        donation: (options: DonationTemplateOptions) => ReturnType<typeof createDonationReceipt>;
+        escrow: (options: EscrowTemplateOptions) => ReturnType<typeof createEscrowReceipt>;
+        grant: (options: GrantTemplateOptions) => ReturnType<typeof createGrantReceipt>;
+        refund: (options: RefundTemplateOptions) => ReturnType<typeof createRefundReceipt>;
+    };
+    constructor(config?: SDKConfig);
+    /**
+     * Create a new project with API key (self-serve)
+     * This is a convenience method for beginners
+     */
+    static createProject(options?: {
+        label?: string;
+        network?: Network;
+        baseUrl?: string;
+    }): Promise<{
+        client: ProofRails;
+        apiKey: string;
+        projectId: string;
+    }>;
+    /**
+     * Update the API key for this client
+     */
+    setApiKey(apiKey: string): void;
+    /**
+     * Update the admin token for this client
+     */
+    setAdminToken(adminToken: string): void;
+}
+
+/**
+ * User-friendly error messages and helpers
+ */
+interface FriendlyError {
+    title: string;
+    message: string;
+    solution?: string;
+    learnMore?: string;
+}
+declare function getFriendlyError(error: any): FriendlyError;
+declare function formatErrorForDisplay(error: any): string;
+
+/**
+ * Smart auto-detection utilities
+ */
+
+interface ChainInfo {
+    id: number;
+    name: string;
+    network: Network;
+    currency: string;
+    rpcUrl: string;
+    explorerUrl: string;
+}
+declare const SUPPORTED_CHAINS: Record<number, ChainInfo>;
+/**
+ * Auto-detect network from chain ID
+ */
+declare function detectNetwork(chainId?: number): Network;
+/**
+ * Auto-detect currency from chain ID
+ */
+declare function detectCurrency(chainId?: number): string;
+/**
+ * Get chain info from chain ID
+ */
+declare function getChainInfo(chainId: number): ChainInfo | null;
+/**
+ * Check if chain is supported
+ */
+declare function isSupportedChain(chainId: number): boolean;
+/**
+ * Get explorer URL for transaction
+ */
+declare function getExplorerUrl(chainId: number, txHash: string): string;
+/**
+ * Get explorer URL for address
+ */
+declare function getAddressExplorerUrl(chainId: number, address: string): string;
+
+/**
+ * Validation helpers for common inputs
+ */
+interface ValidationResult {
+    isValid: boolean;
+    error?: string;
+}
+/**
+ * Validate Ethereum address
+ */
+declare function validateAddress(address: string): ValidationResult;
+/**
+ * Validate amount
+ */
+declare function validateAmount(amount: string | number): ValidationResult;
+/**
+ * Validate transaction hash
+ */
+declare function validateTransactionHash(hash: string): ValidationResult;
+/**
+ * Validate API key format
+ */
+declare function validateApiKey(apiKey: string): ValidationResult;
+/**
+ * Validate purpose/reference text
+ */
+declare function validatePurpose(purpose: string): ValidationResult;
+/**
+ * Validate all payment fields at once
+ */
+declare function validatePayment(params: {
+    amount: string | number;
+    to: string;
+    purpose: string;
+    transactionHash?: string;
+}): ValidationResult;
+
+export { type APIKey, type APIResponse, type ChainInfo, type CreateAPIKeyOptions, type CreateProjectOptions, type CreateReceiptOptions, type DonationTemplateOptions, type EscrowTemplateOptions, type FriendlyError, type GenerateStatementOptions, type GrantTemplateOptions, type ISOMessage, type ISOMessageType, type ListReceiptsOptions, type Network, type PaginatedResponse, type PaymentTemplateOptions, type Project, ProofRails, ProofRailsError, type RateLimitInfo, type Receipt, type ReceiptArtifacts, type ReceiptStatus, type ReceiptUpdate, type RefundTemplateOptions, type SDKConfig, type Receipt as SDKReceipt, SUPPORTED_CHAINS, type Statement, type ValidationResult, type VerificationProof, type VerificationResult, type WhoAmIResponse, ProofRails as default, detectCurrency, detectNetwork, formatErrorForDisplay, getAddressExplorerUrl, getChainInfo, getExplorerUrl, getFriendlyError, isSupportedChain, validateAddress, validateAmount, validateApiKey, validatePayment, validatePurpose, validateTransactionHash };