@algopayoracle/oracle-sdk 1.0.0

package/src/index.d.ts

@@ -0,0 +1,373 @@
+/**
+ * @algopayoracle/oracle-sdk — TypeScript Definitions
+ * APC-1 · Ed25519 · Algorand
+ */
+
+// ─── Core types ───────────────────────────────────────────────────────────────
+
+/** Normalized payment event — the single shape consumed by AlgoPayClient */
+export interface PaymentEvent {
+  /** Provider-issued payment reference (e.g. "pay_XXXXXXX") */
+  payment_id: string;
+  /** Integer fiat amount in base currency units (e.g. 100 for ₹100) */
+  amount: number;
+  /** ISO 4217 currency code (default: "INR") */
+  currency?: string;
+  /** Intended Web3 action (default: "unlock") */
+  action?: string;
+  /** Payment rail label — enables cross-provider replay protection (default: "unknown") */
+  provider?: string;
+}
+
+/** Internal signed proof — output of OracleSigner.sign() */
+export interface SignedProof {
+  /** Original provider-issued ID (display only) */
+  payment_id: string;
+  /** Namespaced replay key: "provider:payment_id" — what was signed and stored on-chain */
+  canonical_id: string;
+  provider: string;
+  amount: number;
+  action: string;
+  currency: string;
+  /** Unix seconds when proof was signed (backdated ~30s for network latency) */
+  timestamp: number;
+  /** The Algorand Application ID this proof is locked to (0 for anchor mode) */
+  app_id: number;
+  /** Algorand address of the signing oracle */
+  oracle_address: string;
+  /** Base64 Ed25519 signature */
+  signature: string;
+}
+
+/** APC-1 (AlgoPay Credential v1) — standardized portable payment proof */
+export interface APC1Proof {
+  /** Format version — always "1" */
+  apc: "1";
+  payment_id: string;
+  /** canonical_id is the on-chain replay key — must be present for verification */
+  canonical_id: string;
+  amount: number;
+  currency: string;
+  action: string;
+  timestamp: number;
+  oracle_address: string;
+  signature: string;
+  chain: "algorand";
+  network: "localnet" | "testnet" | "mainnet";
+  app_id: number | null;
+  provider: string;
+}
+
+/** Result of AlgoPayClient.verifyAndCommit() */
+export interface CommitResult {
+  /** Confirmed Algorand transaction ID */
+  txId: string;
+  /** Internal signed proof */
+  proof: SignedProof;
+  /** APC-1 standardized credential */
+  apc1: APC1Proof;
+  /** Lora explorer link */
+  explorerUrl: string;
+  /** Relative URL for your backend's /verify-proof endpoint */
+  verifyUrl: string;
+  /** Access window in seconds (default: 300) */
+  access_seconds: number;
+}
+
+/** Result of proof verification */
+export interface VerifyResult {
+  valid: boolean;
+  /** Human-readable reason when valid is false */
+  reason?: string;
+  proof?: SignedProof;
+  txId?: string;
+}
+
+/** Options for proof verification */
+export interface VerifyOptions {
+  /** Only accept proofs signed by this oracle address */
+  expectedOracleAddress?: string;
+  /** Only accept proofs with this action */
+  expectedAction?: string;
+  /** Maximum proof age in seconds (default: 300) */
+  maxAgeSecs?: number;
+}
+
+// ─── PaymentAdapter interface ─────────────────────────────────────────────────
+//
+// The adapter contract: any object implementing PaymentAdapter can be used
+// to normalize gateway-specific webhooks into AlgoPay PaymentEvents.
+//
+// Implementing a custom adapter (e.g. PayU, CCAvenue, PhonePe):
+//
+//   class PayUAdapter implements PaymentAdapter {
+//     parseWebhook(rawBody: Buffer, signature: string): PaymentEvent | null {
+//       if (!this.verifyChecksum(rawBody, signature)) return null;
+//       const body = JSON.parse(rawBody.toString());
+//       return {
+//         payment_id: body.mihpayid,
+//         amount:     Math.round(Number(body.amount)),
+//         currency:   "INR",
+//         action:     "unlock",
+//         provider:   "payu",
+//       };
+//     }
+//   }
+
+export interface PaymentAdapter {
+  /**
+   * Parse and verify a gateway webhook event.
+   * Returns null on invalid signature or non-payment events.
+   * Never throws — invalid input returns null.
+   */
+  parseWebhook(rawBody: Buffer | string, signature: string): PaymentEvent | null;
+}
+
+// ─── AlgoPayClient ────────────────────────────────────────────────────────────
+
+export interface AlgoPayClientOptions {
+  /** 25-word Algorand mnemonic for the oracle signing account */
+  mnemonic: string;
+  /** Algorand network (default: "testnet") */
+  network?: "localnet" | "testnet" | "mainnet";
+  /** Deployed AlgoPayOracle App ID. Omit to run in anchor mode. */
+  appId?: number | null;
+  /** Custom algod client (overrides network) */
+  algod?: unknown;
+  /** Custom indexer client */
+  indexer?: unknown;
+  /** Custom explorer base URL */
+  explorerBase?: string;
+}
+
+export declare class AlgoPayClient {
+  readonly network: string;
+  readonly appId: number | null;
+
+  constructor(options: AlgoPayClientOptions);
+
+  /** Sign and commit a payment to Algorand. Primary entry point. */
+  verifyAndCommit(payment: PaymentEvent): Promise<CommitResult>;
+
+  /** Verify a proof by txId (indexer lookup) */
+  verifyProof(txId: string, opts?: VerifyOptions): Promise<VerifyResult>;
+
+  /** Verify a proof off-chain (no network) */
+  verifyProofOffchain(proof: SignedProof, opts?: VerifyOptions): VerifyResult;
+
+  /** Register a new oracle (creator only) */
+  addOracle(addressOrBase64: string): Promise<string>;
+
+  /** Deregister an oracle (creator only) */
+  removeOracle(addressOrBase64: string): Promise<string>;
+
+  /** Check if an oracle is registered in the contract */
+  isOracleRegistered(addressOrBase64: string): Promise<boolean>;
+
+  /** Total verified payments from the contract */
+  getTotalVerified(): Promise<number>;
+
+  /** Number of registered oracles */
+  getOracleCount(): Promise<number>;
+
+  getAddress(): string;
+  getPublicKeyBase64(): string;
+  getPublicKeyBytes(): Uint8Array;
+  getExplorerUrl(txId: string): string;
+}
+
+// ─── OracleSigner ─────────────────────────────────────────────────────────────
+
+export interface SignOptions {
+  payment_id: string;
+  amount: number;
+  action?: string;
+  currency?: string;
+  provider?: string;
+}
+
+export declare class OracleSigner {
+  readonly address: string;
+
+  constructor(mnemonic: string);
+
+  /** Sign a payment proof */
+  sign(options: SignOptions, appId?: number): SignedProof;
+
+  /** Build raw message bytes (must match contract verify_payment exactly) */
+  static buildMessage(
+    canonical_id: string,
+    action: string,
+    currency: string,
+    amount: number,
+    timestamp: number,
+    appId?: number
+  ): Uint8Array;
+
+  /** Verify a proof's signature off-chain */
+  static verifyOffchain(proof: SignedProof): boolean;
+
+  /** Base64 public key — paste into contract create() call */
+  getPublicKeyBase64(): string;
+  getPublicKeyBytes(): Uint8Array;
+  getAddress(): string;
+}
+
+// ─── ProofVerifier ────────────────────────────────────────────────────────────
+
+export interface ProofVerifierOptions {
+  indexer?: unknown;
+  network?: string;
+}
+
+export declare class ProofVerifier {
+  constructor(options?: ProofVerifierOptions);
+
+  verifyOffchain(proof: SignedProof | APC1Proof, opts?: VerifyOptions): VerifyResult;
+  verifyTxn(txId: string, opts?: VerifyOptions): Promise<VerifyResult>;
+  verifyBatch(txIds: string[], opts?: VerifyOptions): Promise<VerifyResult[]>;
+}
+
+// ─── Adapters ─────────────────────────────────────────────────────────────────
+
+export interface OrderRecord {
+  amount: number;
+  currency: string;
+}
+
+export interface OrderStore {
+  set(id: string, data: OrderRecord): Promise<void>;
+  get(id: string): Promise<OrderRecord | null>;
+  consume(id: string): Promise<OrderRecord | null>;
+  delete(id: string): Promise<void>;
+  size?(): number;
+  destroy?(): void;
+}
+
+export interface RazorpayAdapterOptions {
+  keySecret: string;
+  keyId?: string;
+  orderStore?: OrderStore;
+  defaultAction?: string;
+}
+
+export interface RazorpayClientPaymentInput {
+  razorpay_order_id: string;
+  razorpay_payment_id: string;
+  razorpay_signature: string;
+  action?: string;
+}
+
+export declare class RazorpayAdapter implements PaymentAdapter {
+  constructor(options: RazorpayAdapterOptions);
+
+  parseWebhook(rawBody: Buffer | string, signature: string): PaymentEvent | null;
+  parseClientPayment(input: RazorpayClientPaymentInput): Promise<PaymentEvent>;
+  createOrder(opts: { amount: number; currency?: string }): Promise<{ order_id: string; amount: number; currency: string; key_id: string }>;
+}
+
+export interface StripeAdapterOptions {
+  webhookSecret: string;
+  secretKey?: string;
+  defaultAction?: string;
+}
+
+export declare class StripeAdapter implements PaymentAdapter {
+  constructor(options: StripeAdapterOptions);
+  parseWebhook(rawBody: Buffer, signature: string): PaymentEvent | null;
+}
+
+// ─── Utilities ────────────────────────────────────────────────────────────────
+
+export interface NetworkConfig {
+  algodToken: string;
+  algodServer: string;
+  algodPort: number;
+  indexerToken: string;
+  indexerServer: string;
+  indexerPort: number;
+  explorerBase: string;
+}
+
+export declare const NETWORKS: Record<"localnet" | "testnet" | "mainnet", NetworkConfig>;
+
+export declare function createClients(network: "localnet" | "testnet" | "mainnet"): {
+  algod: unknown;
+  indexer: unknown;
+  config: NetworkConfig;
+};
+
+export interface CustomClientOptions {
+  algodUrl: string;
+  algodToken?: string;
+  indexerUrl: string;
+  indexerToken?: string;
+  explorerBase?: string;
+}
+
+export declare function createCustomClients(opts: CustomClientOptions): {
+  algod: unknown;
+  indexer: unknown;
+  config: { explorerBase: string };
+};
+
+export declare const APC_VERSION: "1";
+export declare function toAPC1(proof: SignedProof, meta?: { network?: string; appId?: number | null; provider?: string }): APC1Proof;
+export declare function validateAPC1Structure(cred: unknown): { valid: boolean; errors: string[] };
+export declare function isSupportedVersion(cred: unknown): boolean;
+export declare function isExpired(cred: { timestamp: number }, maxAgeSecs?: number): boolean;
+
+export declare function validatePaymentEvent(input: unknown): PaymentEvent;
+export declare function validateProofFields(proof: unknown): void;
+
+// ─── Logger ───────────────────────────────────────────────────────────────────
+
+export interface Logger {
+  info(msg: string, fields?: Record<string, unknown>): void;
+  warn(msg: string, fields?: Record<string, unknown>): void;
+  error(msg: string, fields?: Record<string, unknown>): void;
+  debug(msg: string, fields?: Record<string, unknown>): void;
+  child(fields: Record<string, unknown>): Logger;
+}
+
+export declare function createLogger(component: string): Logger;
+export declare function requestLogger(req: unknown, res: unknown, next: () => void): void;
+
+// ─── Order store ──────────────────────────────────────────────────────────────
+
+export declare class InMemoryOrderStore implements OrderStore {
+  constructor(ttlMs?: number);
+  set(id: string, data: OrderRecord): Promise<void>;
+  get(id: string): Promise<OrderRecord | null>;
+  consume(id: string): Promise<OrderRecord | null>;
+  delete(id: string): Promise<void>;
+  size(): number;
+  destroy(): void;
+}
+
+export declare function createOrderStore(options?: { ttlMs?: number }): InMemoryOrderStore;
+
+// ─── Error classes ────────────────────────────────────────────────────────────
+
+export declare class AlgoPayError extends Error {
+  code: string;
+}
+export declare class InsufficientAmountError extends AlgoPayError {
+  amount: number;
+  minAmount: number;
+}
+export declare class ProofExpiredError extends AlgoPayError {
+  timestamp: number;
+  age: number;
+}
+export declare class OracleNotRegisteredError extends AlgoPayError {
+  address: string;
+}
+export declare class ReplayError extends AlgoPayError {
+  paymentId: string;
+}
+export declare class InvalidSignatureError extends AlgoPayError {}
+export declare class ConfigError extends AlgoPayError {}
+export declare class ProviderAuthError extends AlgoPayError {
+  provider: string;
+}

package/src/index.js

@@ -0,0 +1,99 @@
+/**
+ * @algopayoracle/oracle-sdk
+ *
+ * Everything you need is available from this single entry point.
+ * You should never need to import from internal paths.
+ *
+ * Common usage:
+ *
+ *   const { AlgoPayClient } = require("@algopayoracle/oracle-sdk");
+ *
+ *   const client = new AlgoPayClient({
+ *     mnemonic: process.env.ORACLE_MNEMONIC,
+ *     network:  "testnet",
+ *     appId:    Number(process.env.ALGO_APP_ID),
+ *   });
+ *
+ *   const result = await client.verifyAndCommit({
+ *     payment_id: "pay_XXXXXXX",
+ *     amount:     100,
+ *     action:     "unlock",
+ *     provider:   "razorpay",
+ *   });
+ */
+
+"use strict";
+
+// ── Core client (most users only need this) ───────────────────────────────────
+const { AlgoPayClient }  = require("./AlgoPayClient");
+const { OracleSigner }   = require("./OracleSigner");
+const { ProofVerifier }  = require("./ProofVerifier");
+
+// ── Network helpers ────────────────────────────────────────────────────────────
+const { NETWORKS, createClients, createCustomClients } = require("./networks");
+
+// ── APC-1 standard ────────────────────────────────────────────────────────────
+const {
+  APC_VERSION,
+  SUPPORTED_APC,
+  toAPC1,
+  validateAPC1Structure,
+  isSupportedVersion,
+  isExpired,
+} = require("./apc1");
+
+// ── Input validation ──────────────────────────────────────────────────────────
+const { validatePaymentEvent, validateProofFields, MIN_AMOUNT } = require("./validate");
+
+// ── Error classes ─────────────────────────────────────────────────────────────
+const errors = require("./errors");
+
+// ── Payment adapters ──────────────────────────────────────────────────────────
+const { RazorpayAdapter } = require("./adapters/razorpay");
+const { StripeAdapter }   = require("./adapters/stripe");
+
+// ── Infrastructure utilities ──────────────────────────────────────────────────
+const { createLogger, requestLogger } = require("./utils/logger");
+const { createOrderStore, InMemoryOrderStore } = require("./utils/store");
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  // Primary API
+  AlgoPayClient,
+
+  // Lower-level building blocks
+  OracleSigner,
+  ProofVerifier,
+
+  // Network
+  NETWORKS,
+  createClients,
+  createCustomClients,
+
+  // APC-1 standard
+  APC_VERSION,
+  SUPPORTED_APC,
+  toAPC1,
+  validateAPC1Structure,
+  isSupportedVersion,
+  isExpired,
+
+  // Input validation
+  validatePaymentEvent,
+  validateProofFields,
+  MIN_AMOUNT,
+
+  // Error classes (spread so consumers can do { AlgoPayError } = require(...))
+  ...errors,
+
+  // Adapters
+  RazorpayAdapter,
+  StripeAdapter,
+
+  // Infrastructure
+  createLogger,
+  requestLogger,
+  createOrderStore,
+  InMemoryOrderStore,
+};

package/src/networks.js

@@ -0,0 +1,66 @@
+/**
+ * AlgoPay Oracle SDK — Network Configurations
+ */
+
+const algosdk = require("algosdk");
+
+const NETWORKS = {
+  localnet: {
+    algodToken:    "a".repeat(64),
+    algodServer:   "http://localhost",
+    algodPort:     4001,
+    indexerToken:  "a".repeat(64),
+    indexerServer: "http://localhost",
+    indexerPort:   8980,
+    explorerBase:  "https://lora.algokit.io/localnet",
+  },
+  testnet: {
+    algodToken:    "",
+    algodServer:   "https://testnet-api.algonode.cloud",
+    algodPort:     443,
+    indexerToken:  "",
+    indexerServer: "https://testnet-idx.algonode.cloud",
+    indexerPort:   443,
+    explorerBase:  "https://lora.algokit.io/testnet",
+  },
+  mainnet: {
+    algodToken:    "",
+    algodServer:   "https://mainnet-api.algonode.cloud",
+    algodPort:     443,
+    indexerToken:  "",
+    indexerServer: "https://mainnet-idx.algonode.cloud",
+    indexerPort:   443,
+    explorerBase:  "https://lora.algokit.io/mainnet",
+  },
+};
+
+/**
+ * Create algod + indexer clients for a named network.
+ * @param {"localnet"|"testnet"|"mainnet"} network
+ * @returns {{ algod: Algodv2, indexer: Indexer, config: object }}
+ */
+function createClients(network) {
+  const cfg = NETWORKS[network];
+  if (!cfg) throw new Error(`Unknown network: ${network}. Use localnet, testnet, or mainnet.`);
+  return {
+    algod:   new algosdk.Algodv2(cfg.algodToken, cfg.algodServer, cfg.algodPort),
+    indexer: new algosdk.Indexer(cfg.indexerToken, cfg.indexerServer, cfg.indexerPort),
+    config:  cfg,
+  };
+}
+
+/**
+ * Create clients from custom algod/indexer URLs (e.g. nodely, purestake).
+ * @param {{ algodUrl, algodToken, indexerUrl, indexerToken, explorerBase }} opts
+ */
+function createCustomClients({ algodUrl, algodToken = "", indexerUrl, indexerToken = "", explorerBase = "" }) {
+  const algodUri   = new URL(algodUrl);
+  const indexerUri = new URL(indexerUrl);
+  return {
+    algod:   new algosdk.Algodv2(algodToken,   algodUri.origin,   algodUri.port || 443),
+    indexer: new algosdk.Indexer(indexerToken, indexerUri.origin, indexerUri.port || 443),
+    config:  { explorerBase },
+  };
+}
+
+module.exports = { NETWORKS, createClients, createCustomClients };

package/src/utils/logger.js

@@ -0,0 +1,98 @@
+/**
+ * AlgoPay Oracle — Structured Logger
+ *
+ * Outputs JSON in production (machine-parseable, ingestible by Datadog/Loki/CloudWatch).
+ * Outputs pretty-printed lines in development.
+ *
+ * Every log entry carries a requestId so a full payment flow can be traced
+ * across multiple log lines: create-order → verify-payment → oracle sign → txId.
+ *
+ * Usage:
+ *   const { createLogger, requestLogger } = require("./logger");
+ *   const log = createLogger("payment");
+ *   log.info("Payment received", { payment_id, amount });
+ *   log.error("Oracle failed", { payment_id, error: e.message });
+ *
+ * Express middleware:
+ *   app.use(requestLogger);   // attaches req.log and req.requestId
+ *   // then in routes:
+ *   req.log.info("order created", { order_id, amount });
+ */
+
+"use strict";
+
+const crypto  = require("crypto");
+const IS_PROD = process.env.NODE_ENV === "production";
+
+// ─── Core log function ────────────────────────────────────────────────────────
+
+function write(level, component, message, fields = {}) {
+  const entry = {
+    ts:        new Date().toISOString(),
+    level,
+    component,
+    message,
+    ...fields,
+  };
+
+  if (IS_PROD) {
+    // JSON — one line per entry, ready for log aggregators
+    process.stdout.write(JSON.stringify(entry) + "\n");
+  } else {
+    // Human-readable dev format
+    const color = { info: "\x1b[32m", warn: "\x1b[33m", error: "\x1b[31m", debug: "\x1b[90m" };
+    const reset = "\x1b[0m";
+    const c     = color[level] || "";
+    const meta  = Object.keys(fields).length
+      ? "  " + Object.entries(fields).map(([k, v]) => `${k}=${v}`).join("  ")
+      : "";
+    console.log(`${c}[${entry.ts}] ${level.toUpperCase().padEnd(5)} [${component}] ${message}${meta}${reset}`);
+  }
+}
+
+// ─── Logger factory ───────────────────────────────────────────────────────────
+
+function createLogger(component) {
+  return {
+    info:  (msg, fields) => write("info",  component, msg, fields),
+    warn:  (msg, fields) => write("warn",  component, msg, fields),
+    error: (msg, fields) => write("error", component, msg, fields),
+    debug: (msg, fields) => {
+      if (!IS_PROD) write("debug", component, msg, fields);
+    },
+    // Returns a child logger with fixed fields merged into every entry
+    child: (fixedFields) => ({
+      info:  (msg, fields) => write("info",  component, msg, { ...fixedFields, ...fields }),
+      warn:  (msg, fields) => write("warn",  component, msg, { ...fixedFields, ...fields }),
+      error: (msg, fields) => write("error", component, msg, { ...fixedFields, ...fields }),
+      debug: (msg, fields) => {
+        if (!IS_PROD) write("debug", component, msg, { ...fixedFields, ...fields });
+      },
+    }),
+  };
+}
+
+// ─── Express request logger middleware ────────────────────────────────────────
+
+const httpLog = createLogger("http");
+
+function requestLogger(req, res, next) {
+  req.requestId = crypto.randomUUID();
+  req.log       = httpLog.child({ requestId: req.requestId });
+
+  const start = Date.now();
+
+  res.on("finish", () => {
+    const ms = Date.now() - start;
+    const level = res.statusCode >= 500 ? "error" : res.statusCode >= 400 ? "warn" : "info";
+    write(level, "http", `${req.method} ${req.path}`, {
+      requestId:  req.requestId,
+      status:     res.statusCode,
+      ms,
+    });
+  });
+
+  next();
+}
+
+module.exports = { createLogger, requestLogger };