@proofrails/sdk 1.3.0 → 1.5.0

package/dist/sdk-DUtEmkhW.d.ts

@@ -0,0 +1,459 @@
+/**
+ * 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;
+}
+
+export { type APIResponse as A, type CreateProjectOptions as C, type DonationTemplateOptions as D, type EscrowTemplateOptions as E, type GrantTemplateOptions as G, type ISOMessageType as I, type ListReceiptsOptions as L, type Network as N, ProofRails as P, type Receipt as R, type SDKConfig as S, type VerificationResult as V, type WhoAmIResponse as W, type PaymentTemplateOptions as a, type RefundTemplateOptions as b, ProofRailsError as c, type RateLimitInfo as d, type ReceiptStatus as e, type PaginatedResponse as f, type Project as g, type APIKey as h, type CreateAPIKeyOptions as i, type CreateReceiptOptions as j, type ReceiptArtifacts as k, type ReceiptUpdate as l, type ISOMessage as m, type GenerateStatementOptions as n, type Statement as o, type VerificationProof as p };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@proofrails/sdk",
-    "version": "1.3.0",
+    "version": "1.5.0",
     "description": "Beginner-friendly SDK for ProofRails ISO 20022 Middleware - Create blockchain-verifiable payment receipts with zero coding knowledge",
     "main": "dist/index.js",
     "module": "dist/index.mjs",
@@ -29,7 +29,10 @@
     },
     "files": [
         "dist",
-        "README.md"
+        "README.md",
+        "BEGINNER_GUIDE.md",
+        "PRODUCTION_GUIDE.md",
+        ".env.example"
     ],
     "scripts": {
         "build": "tsup",