@algopayoracle/oracle-sdk 1.0.1 → 1.0.4

package/examples/custom-adapter.js

@@ -0,0 +1,252 @@
+/**
+ * @algopayoracle/oracle-sdk — Custom Payment Adapter Example
+ *
+ * Demonstrates how to integrate any payment gateway with AlgoPay Oracle.
+ * The SDK's core (AlgoPayClient) only speaks PaymentEvent.
+ * Your adapter is the translation layer between your gateway and PaymentEvent.
+ *
+ * This file shows three adapters:
+ *   1. PayUAdapter     — real-world Indian payment gateway
+ *   2. PhonePeAdapter  — UPI-native gateway
+ *   3. GenericAdapter  — minimal template to copy for any provider
+ *
+ * The PaymentAdapter interface (from index.d.ts):
+ *
+ *   interface PaymentAdapter {
+ *     parseWebhook(rawBody: Buffer | string, signature: string): PaymentEvent | null;
+ *   }
+ *
+ * Rules for a correct adapter:
+ *   1. Verify the gateway's own signature/checksum before trusting any field
+ *   2. Return null (never throw) on invalid signature or non-payment events
+ *   3. Amount must come from the gateway payload — never from the request body directly
+ *   4. Set provider so canonical_id = "provider:payment_id" is unique per rail
+ */
+
+"use strict";
+
+const crypto = require("crypto");
+const { AlgoPayClient } = require("../src");
+
+// ════════════════════════════════════════════════════════════════════════════
+//  1. PayUAdapter — PayU India
+//     Docs: https://devguide.payu.in/webhook/webhook-overview/
+// ════════════════════════════════════════════════════════════════════════════
+
+class PayUAdapter {
+  /**
+   * @param {object} opts
+   * @param {string} opts.merchantSalt  - PayU merchant salt
+   * @param {string} [opts.defaultAction]
+   */
+  constructor({ merchantSalt, defaultAction = "unlock" }) {
+    if (!merchantSalt) throw new Error("PayUAdapter: merchantSalt is required");
+    this.merchantSalt  = merchantSalt;
+    this.defaultAction = defaultAction;
+  }
+
+  /**
+   * PayU sends a hash in the payload for webhook verification.
+   * Hash formula (reverse): sha512(salt|status||||||udf5|udf4|udf3|udf2|udf1|email|productinfo|amount|txnid|key)
+   */
+  parseWebhook(rawBody, _signature) {
+    let body;
+    try { body = Object.fromEntries(new URLSearchParams(rawBody.toString())); }
+    catch { return null; }
+
+    if (body.status !== "success") return null;
+    if (!body.txnid || !body.amount) return null;
+
+    // Verify PayU hash (simplified — see PayU docs for full field list)
+    const hashString = [
+      this.merchantSalt,
+      body.status,
+      "", "", "", "",                        // udf5–udf2 (empty if not used)
+      body.udf1 || "",
+      body.email || "",
+      body.productinfo || "",
+      body.amount,
+      body.txnid,
+      body.key,
+    ].join("|");
+
+    const expectedHash = crypto.createHash("sha512").update(hashString).digest("hex");
+    if (body.hash !== expectedHash) return null;
+
+    return {
+      payment_id: body.txnid,
+      amount:     Math.round(Number(body.amount)),  // PayU sends as string "100.00"
+      currency:   "INR",
+      action:     this.defaultAction,
+      provider:   "payu",
+    };
+  }
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+//  2. PhonePeAdapter — PhonePe Business
+//     Docs: https://developer.phonepe.com/v1/reference/check-status-api
+// ════════════════════════════════════════════════════════════════════════════
+
+class PhonePeAdapter {
+  /**
+   * @param {object} opts
+   * @param {string} opts.saltKey    - PhonePe salt key
+   * @param {number} opts.saltIndex  - PhonePe salt index (usually 1)
+   * @param {string} [opts.defaultAction]
+   */
+  constructor({ saltKey, saltIndex = 1, defaultAction = "unlock" }) {
+    if (!saltKey) throw new Error("PhonePeAdapter: saltKey is required");
+    this.saltKey       = saltKey;
+    this.saltIndex     = saltIndex;
+    this.defaultAction = defaultAction;
+  }
+
+  /**
+   * PhonePe sends X-VERIFY header: sha256(base64payload + "/pg/v1/pay" + salt) + "###" + saltIndex
+   */
+  parseWebhook(rawBody, xVerifyHeader) {
+    if (!xVerifyHeader) return null;
+
+    const [receivedHash, receivedIndex] = xVerifyHeader.split("###");
+    if (Number(receivedIndex) !== this.saltIndex) return null;
+
+    const base64Body    = Buffer.from(rawBody).toString("base64");
+    const hashInput     = base64Body + "/pg/v1/pay" + this.saltKey;
+    const expectedHash  = crypto.createHash("sha256").update(hashInput).digest("hex");
+
+    if (receivedHash !== expectedHash) return null;
+
+    let parsed;
+    try { parsed = JSON.parse(Buffer.from(base64Body, "base64").toString()); }
+    catch { return null; }
+
+    const data = parsed?.data;
+    if (!data?.merchantTransactionId || !data?.amount) return null;
+    if (parsed?.code !== "PAYMENT_SUCCESS") return null;
+
+    return {
+      payment_id: data.merchantTransactionId,
+      amount:     Math.round(data.amount / 100),  // PhonePe sends in paise
+      currency:   "INR",
+      action:     this.defaultAction,
+      provider:   "phonepe",
+    };
+  }
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+//  3. GenericAdapter — minimal copy-paste template
+//
+//  Steps to adapt for any gateway:
+//    a) Replace verifySignature() with your gateway's HMAC/checksum method
+//    b) Map gateway fields → payment_id, amount, currency
+//    c) Set provider to a unique lowercase label
+// ════════════════════════════════════════════════════════════════════════════
+
+class GenericAdapter {
+  constructor({ secret, defaultAction = "unlock" }) {
+    this.secret        = secret;
+    this.defaultAction = defaultAction;
+  }
+
+  parseWebhook(rawBody, signature) {
+    // a) Verify signature — replace this with your gateway's method
+    if (!this._verifySignature(rawBody, signature)) return null;
+
+    let body;
+    try { body = JSON.parse(rawBody.toString()); }
+    catch { return null; }
+
+    // b) Only process payment success events
+    if (body.event_type !== "payment.success") return null;
+
+    // c) Map to PaymentEvent
+    return {
+      payment_id: body.transaction_id,              // gateway's unique ID
+      amount:     Math.round(Number(body.amount)),  // always integer
+      currency:   (body.currency || "INR").toUpperCase(),
+      action:     this.defaultAction,
+      provider:   "mygateway",                      // your unique label
+    };
+  }
+
+  _verifySignature(rawBody, signature) {
+    // Replace with your gateway's actual verification
+    const expected = crypto
+      .createHmac("sha256", this.secret)
+      .update(rawBody)
+      .digest("hex");
+    const received = Buffer.from(signature || "", "hex");
+    if (expected.length !== received.length) return false;
+    return crypto.timingSafeEqual(Buffer.from(expected, "hex"), received);
+  }
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+//  Wiring into Express (same pattern for all adapters)
+// ════════════════════════════════════════════════════════════════════════════
+
+function wireAdapter(app, path, adapter, client, limiter) {
+  app.post(path, limiter, async (req, res) => {
+    // Every adapter implements the same parseWebhook interface
+    const event = adapter.parseWebhook(
+      req.rawBody,
+      req.headers["x-signature"] || req.headers["x-verify"] || req.headers["x-razorpay-signature"]
+    );
+
+    if (!event) return res.status(401).json({ error: "invalid webhook signature" });
+
+    try {
+      const result = await client.verifyAndCommit(event);
+      res.json({ received: true, txId: result.txId });
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  });
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Demo: all three adapters wired to the same client
+// ────────────────────────────────────────────────────────────────────────────
+
+if (require.main === module) {
+  require("dotenv").config();
+
+  const express = require("express");
+  const app     = express();
+  const client  = new AlgoPayClient({
+    mnemonic: process.env.ORACLE_MNEMONIC,
+    network:  process.env.ALGO_NETWORK || "testnet",
+    appId:    process.env.ALGO_APP_ID ? Number(process.env.ALGO_APP_ID) : null,
+  });
+
+  // Raw body middleware
+  app.use((req, _res, next) => {
+    const chunks = [];
+    req.on("data", c => chunks.push(c));
+    req.on("end", () => {
+      req.rawBody = Buffer.concat(chunks);
+      try { req.body = JSON.parse(req.rawBody); } catch { req.body = {}; }
+      next();
+    });
+  });
+
+  const noopLimiter = (_req, _res, next) => next();  // replace with express-rate-limit in production
+
+  if (process.env.PAYU_SALT) {
+    const payu = new PayUAdapter({ merchantSalt: process.env.PAYU_SALT });
+    wireAdapter(app, "/webhook/payu", payu, client, noopLimiter);
+    console.log("PayU adapter wired → POST /webhook/payu");
+  }
+
+  if (process.env.PHONEPE_SALT) {
+    const phonepe = new PhonePeAdapter({ saltKey: process.env.PHONEPE_SALT });
+    wireAdapter(app, "/webhook/phonepe", phonepe, client, noopLimiter);
+    console.log("PhonePe adapter wired → POST /webhook/phonepe");
+  }
+
+  app.listen(5000, () => console.log("Custom adapter demo → http://localhost:5000"));
+}
+
+module.exports = { PayUAdapter, PhonePeAdapter, GenericAdapter };

package/examples/express-webhook.js

@@ -0,0 +1,390 @@
+/**
+ * @algopayoracle/oracle-sdk — Production Express Server Example
+ *
+ * This is the reference implementation for integrating the SDK into a
+ * production Express backend. Copy and adapt to your project.
+ *
+ * TWO SERVERS:
+ *   Public (PORT, 0.0.0.0)         — webhooks, payment verify, proof lookup
+ *   Admin  (ADMIN_PORT, 127.0.0.1) — oracle rotation, stats
+ *
+ * Run:
+ *   node examples/express-webhook.js
+ */
+
+"use strict";
+require("dotenv").config();
+
+const express   = require("express");
+const cors      = require("cors");
+const rateLimit = require("express-rate-limit");
+const crypto    = require("crypto");
+
+const {
+  AlgoPayClient,
+  RazorpayAdapter,
+  createLogger,
+  createOrderStore,
+} = require("../src");
+
+// ─── Environment validation ───────────────────────────────────────────────────
+
+const IS_PRODUCTION = process.env.NODE_ENV === "production";
+const DEMO_MODE     = process.env.DEMO_MODE === "true" && !IS_PRODUCTION;
+
+const log = createLogger("server");
+
+function requireEnv(name) {
+  const val = process.env[name];
+  if (!val) { log.error(`${name} is required but not set`); process.exit(1); }
+  return val;
+}
+
+requireEnv("ORACLE_MNEMONIC");
+if (IS_PRODUCTION) {
+  requireEnv("ADMIN_API_KEY");
+  requireEnv("ALLOWED_ORIGINS");
+} else {
+  if (!process.env.ADMIN_API_KEY) log.warn("ADMIN_API_KEY not set — admin server unprotected");
+  if (!process.env.ALGO_APP_ID)   log.warn("ALGO_APP_ID not set — running in anchor mode");
+}
+
+// ─── Oracle client ────────────────────────────────────────────────────────────
+
+const client = new AlgoPayClient({
+  mnemonic: process.env.ORACLE_MNEMONIC,
+  network:  process.env.ALGO_NETWORK || "testnet",
+  appId:    process.env.ALGO_APP_ID ? Number(process.env.ALGO_APP_ID) : null,
+});
+
+log.info("Oracle initialised", {
+  address: client.getAddress(),
+  network: process.env.ALGO_NETWORK || "testnet",
+  app_id:  client.appId ?? "anchor mode",
+});
+
+// ─── Order store ──────────────────────────────────────────────────────────────
+// In-memory by default. Set REDIS_URL to use Redis (see store.js for interface).
+
+const orderStore = createOrderStore();
+
+// ─── Razorpay adapter (optional) ──────────────────────────────────────────────
+
+const razorpay = (process.env.RAZORPAY_KEY_ID && process.env.RAZORPAY_KEY_SECRET)
+  ? new RazorpayAdapter({
+      keyId:      process.env.RAZORPAY_KEY_ID,
+      keySecret:  process.env.RAZORPAY_KEY_SECRET,
+      orderStore,   // shared so createOrder amounts are enforced in parseClientPayment
+    })
+  : null;
+
+// ─── Shared middleware ─────────────────────────────────────────────────────────
+
+const MAX_BODY = 512 * 1024;
+
+function rawBody(req, res, next) {
+  const chunks = [];
+  let size = 0;
+  req.on("data", chunk => {
+    size += chunk.length;
+    if (size > MAX_BODY) { req.destroy(); return res.status(413).json({ error: "body too large" }); }
+    chunks.push(chunk);
+  });
+  req.on("end", () => {
+    req.rawBody = Buffer.concat(chunks);
+    try { req.body = JSON.parse(req.rawBody.toString()); } catch { req.body = {}; }
+    next();
+  });
+}
+
+function requestLogger(req, res, next) {
+  req.requestId = crypto.randomUUID();
+  req.log       = log.child({ requestId: req.requestId });
+  const start   = Date.now();
+  res.on("finish", () => {
+    const level = res.statusCode >= 500 ? "error" : res.statusCode >= 400 ? "warn" : "info";
+    req.log[level](`${req.method} ${req.path}`, { status: res.statusCode, ms: Date.now() - start });
+  });
+  next();
+}
+
+function requireAdminKey(req, res, next) {
+  const key = process.env.ADMIN_API_KEY;
+  if (!key) return res.status(503).json({ error: "ADMIN_API_KEY not configured" });
+  if (req.headers["x-admin-key"] !== key) return res.status(401).json({ error: "unauthorized" });
+  next();
+}
+
+function sendError(res, status, message, err, reqLog) {
+  const logger = reqLog || log;
+  if (err) logger.error(message, { error: err.message });
+  res.status(status).json({ error: IS_PRODUCTION ? message : (err?.message || message) });
+}
+
+// ─── Rate limiters ────────────────────────────────────────────────────────────
+
+const limiterDefault = rateLimit({
+  windowMs: 60 * 1000, max: 60,
+  standardHeaders: true, legacyHeaders: false,
+  message: { error: "too many requests" },
+});
+
+const limiterPayment = rateLimit({
+  windowMs: 60 * 1000, max: 10,   // each verify-payment triggers an on-chain tx
+  standardHeaders: true, legacyHeaders: false,
+  message: { error: "too many payment requests" },
+});
+
+const limiterWebhook = rateLimit({
+  windowMs: 60 * 1000, max: 120,  // higher — legitimate burst from provider is possible
+  standardHeaders: true, legacyHeaders: false,
+  message: { error: "too many requests" },
+});
+
+// ════════════════════════════════════════════════════════════════════════════
+//  PUBLIC SERVER
+// ════════════════════════════════════════════════════════════════════════════
+
+const publicApp = express();
+
+const allowedOrigins = process.env.ALLOWED_ORIGINS
+  ? process.env.ALLOWED_ORIGINS.split(",").map(s => s.trim())
+  : ["http://localhost:5173", "http://localhost:3000"];
+
+publicApp.use(cors({ origin: allowedOrigins, methods: ["GET", "POST"] }));
+publicApp.use(requestLogger);
+publicApp.use(rawBody);
+
+publicApp.get("/health", limiterDefault, async (_req, res) => {
+  try {
+    const status = await client.algod.status().do();
+    res.json({ ok: true, network: client.network, round: Number(status["last-round"]), demo_mode: DEMO_MODE });
+  } catch (e) {
+    res.status(503).json({ ok: false, error: IS_PRODUCTION ? "algod unreachable" : e.message });
+  }
+});
+
+publicApp.get("/oracle/info", limiterDefault, (_req, res) => {
+  res.json({ address: client.getAddress(), pubkey_base64: client.getPublicKeyBase64(), network: client.network, app_id: client.appId });
+});
+
+// POST /create-order
+// Step 1 of payment flow — get an order ID before opening checkout UI.
+// Amount is stored server-side here and enforced in /verify-payment.
+publicApp.post("/create-order", limiterPayment, async (req, res) => {
+  const amount   = Math.round(Number(req.body.amount || 100));
+  const currency = (req.body.currency || "INR").toUpperCase();
+
+  if (!Number.isInteger(amount) || amount <= 0) {
+    return res.status(400).json({ error: "amount must be a positive integer" });
+  }
+
+  if (razorpay) {
+    try {
+      // createOrder writes to orderStore internally via the shared reference
+      const order = await razorpay.createOrder({ amount, currency });
+      req.log.info("order created", { order_id: order.order_id, amount, provider: "razorpay" });
+      return res.json({ provider: "razorpay", ...order });
+    } catch (e) {
+      return sendError(res, 502, "order creation failed", e, req.log);
+    }
+  }
+
+  if (DEMO_MODE) {
+    const order_id = `demo_${Date.now()}_${crypto.randomBytes(4).toString("hex")}`;
+    await orderStore.set(order_id, { amount, currency });
+    req.log.info("demo order created", { order_id, amount });
+    return res.json({ provider: "demo", order_id, amount, currency, key_id: null });
+  }
+
+  res.status(503).json({
+    error: "no payment provider configured",
+    hint:  IS_PRODUCTION ? "configure RAZORPAY_KEY_ID/SECRET" : "set DEMO_MODE=true for local dev",
+  });
+});
+
+// POST /webhook/razorpay — server-to-server from Razorpay on payment.captured
+publicApp.post("/webhook/razorpay", limiterWebhook, async (req, res) => {
+  if (!razorpay) return res.status(503).json({ error: "Razorpay not configured" });
+
+  const event = razorpay.parseWebhook(req.rawBody, req.headers["x-razorpay-signature"]);
+  if (!event) {
+    req.log.warn("webhook rejected — invalid signature");
+    return res.status(401).json({ error: "invalid signature" });
+  }
+
+  req.log.info("webhook received", { payment_id: event.payment_id, amount: event.amount });
+
+  try {
+    const result = await client.verifyAndCommit(event);
+    req.log.info("webhook committed", { payment_id: event.payment_id, txId: result.txId });
+    res.json({ received: true, txId: result.txId });
+  } catch (e) {
+    sendError(res, 500, "oracle submission failed", e, req.log);
+  }
+});
+
+// POST /verify-payment — frontend calls this after checkout success
+// Amount is ALWAYS resolved from orderStore — never from request body.
+publicApp.post("/verify-payment", limiterPayment, async (req, res) => {
+  const { razorpay_order_id, razorpay_payment_id, razorpay_signature, order_id, action = "unlock" } = req.body;
+  const isRazorpay = razorpay_payment_id && razorpay_signature;
+  let event;
+
+  if (isRazorpay) {
+    if (!razorpay) return res.status(503).json({ success: false, error: "Razorpay not configured" });
+    try {
+      // parseClientPayment: verifies HMAC, resolves amount from orderStore (never client body)
+      event = await razorpay.parseClientPayment({ razorpay_order_id, razorpay_payment_id, razorpay_signature, action });
+    } catch (e) {
+      req.log.warn("client payment rejected", { error: e.message });
+      return res.status(401).json({ success: false, error: e.message });
+    }
+    req.log.info("Razorpay payment verified", { payment_id: event.payment_id, amount: event.amount });
+
+  } else {
+    if (!DEMO_MODE) {
+      return res.status(503).json({
+        success: false,
+        error: IS_PRODUCTION ? "demo mode disabled in production" : "set DEMO_MODE=true",
+      });
+    }
+    const effectiveId = razorpay_order_id || order_id;
+    const record = await orderStore.consume(effectiveId);
+    if (!record) return res.status(400).json({ success: false, error: "order not found or expired — call /create-order first" });
+
+    await new Promise(r => setTimeout(r, 600));
+    event = { payment_id: `demo_${Date.now()}`, amount: record.amount, currency: record.currency, action, provider: "demo" };
+    req.log.info("demo payment", { amount: event.amount, action });
+  }
+
+  try {
+    const result = await client.verifyAndCommit(event);
+    req.log.info("payment committed on-chain", { payment_id: event.payment_id, txId: result.txId });
+    res.json({ success: true, ...result });
+  } catch (e) {
+    sendError(res, 500, "oracle submission failed", e, req.log);
+  }
+});
+
+// GET /verify-proof/:txId — frontend polls this to confirm on-chain proof
+publicApp.get("/verify-proof/:txId", limiterDefault, async (req, res) => {
+  try {
+    const result = await client.verifyProof(req.params.txId);
+    res.json(result);
+  } catch (e) {
+    sendError(res, 500, "verification failed", e, req.log);
+  }
+});
+
+// ─── Generic gateway (any provider pattern — documented, not wired) ───────────
+//
+//   publicApp.post("/webhook/payu", limiterWebhook, async (req, res) => {
+//     if (!verifyPayUChecksum(req.rawBody, req.headers["x-payu-checksum"])) {
+//       return res.status(401).end();
+//     }
+//     const result = await client.verifyAndCommit({
+//       payment_id: req.body.mihpayid,
+//       amount:     Math.round(Number(req.body.amount)),
+//       currency:   "INR",
+//       action:     "unlock",
+//       provider:   "payu",
+//     });
+//     res.json({ received: true, txId: result.txId });
+//   });
+
+// ════════════════════════════════════════════════════════════════════════════
+//  ADMIN SERVER  (127.0.0.1 only)
+// ════════════════════════════════════════════════════════════════════════════
+
+const adminApp  = express();
+const adminLog  = log.child({ server: "admin" });
+
+adminApp.use(rawBody);
+adminApp.use(requireAdminKey);
+
+adminApp.get("/status", async (_req, res) => {
+  const info = {
+    address:     client.getAddress(),
+    network:     client.network,
+    app_id:      client.appId,
+    demo_mode:   DEMO_MODE,
+    node_env:    process.env.NODE_ENV || "development",
+    order_store: { type: "in-memory", size: orderStore.size?.() ?? "unknown" },
+  };
+  if (client.appId) {
+    try {
+      info.total_verified = await client.getTotalVerified();
+      info.oracle_count   = await client.getOracleCount();
+    } catch (e) {
+      info.contract_error = IS_PRODUCTION ? "unreachable" : e.message;
+    }
+  }
+  res.json(info);
+});
+
+adminApp.post("/oracle/add", async (req, res) => {
+  const { address } = req.body;
+  if (!address) return res.status(400).json({ error: "address required" });
+  try {
+    const txId = await client.addOracle(address);
+    adminLog.info("oracle added", { address, txId });
+    res.json({ success: true, txId, added: address });
+  } catch (e) {
+    adminLog.error("addOracle failed", { address, error: e.message });
+    res.status(500).json({ success: false, error: e.message });
+  }
+});
+
+adminApp.post("/oracle/remove", async (req, res) => {
+  const { address } = req.body;
+  if (!address) return res.status(400).json({ error: "address required" });
+  try {
+    const txId = await client.removeOracle(address);
+    adminLog.info("oracle removed", { address, txId });
+    res.json({ success: true, txId, removed: address });
+  } catch (e) {
+    adminLog.error("removeOracle failed", { address, error: e.message });
+    res.status(500).json({ success: false, error: e.message });
+  }
+});
+
+adminApp.get("/oracle/check", async (req, res) => {
+  const { address } = req.query;
+  if (!address) return res.status(400).json({ error: "address query param required" });
+  try {
+    const registered = await client.isOracleRegistered(address);
+    res.json({ address, registered });
+  } catch (e) {
+    res.status(500).json({ error: e.message });
+  }
+});
+
+// ─── Shutdown ─────────────────────────────────────────────────────────────────
+
+function shutdown(signal) {
+  log.info(`${signal} — shutting down`);
+  orderStore.destroy?.();
+  process.exit(0);
+}
+process.on("SIGTERM", () => shutdown("SIGTERM"));
+process.on("SIGINT",  () => shutdown("SIGINT"));
+
+// ─── Start ────────────────────────────────────────────────────────────────────
+
+const PUBLIC_PORT = Number(process.env.PORT       || 5000);
+const ADMIN_PORT  = Number(process.env.ADMIN_PORT || 5001);
+
+publicApp.listen(PUBLIC_PORT, () => {
+  log.info("Public server started", { port: PUBLIC_PORT, bind: "0.0.0.0" });
+  log.info(`Razorpay: ${razorpay ? "configured" : "not configured"}`);
+  log.info(`Demo mode: ${DEMO_MODE}`);
+});
+
+adminApp.listen(ADMIN_PORT, "127.0.0.1", () => {
+  log.info("Admin server started", { port: ADMIN_PORT, bind: "127.0.0.1" });
+  if (IS_PRODUCTION && !process.env.ADMIN_API_KEY) {
+    log.error("ADMIN_API_KEY required in production");
+    process.exit(1);
+  }
+});

package/examples/quickstart.js

@@ -0,0 +1,67 @@
+/**
+ * @algopayoracle/oracle-sdk — Quickstart
+ *
+ * Demonstrates anchor mode (no contract needed).
+ * A real payment proof is signed and anchored on Algorand TestNet.
+ *
+ * Run:
+ *   ORACLE_MNEMONIC="your 25 words" node examples/quickstart.js
+ */
+
+require("dotenv").config();
+const { AlgoPayClient, OracleSigner } = require("../src");
+
+async function main() {
+  const mnemonic = process.env.ORACLE_MNEMONIC;
+  if (!mnemonic) {
+    console.error("Set ORACLE_MNEMONIC in your environment or .env file");
+    process.exit(1);
+  }
+
+  // ── 1. Inspect oracle identity ─────────────────────────────────────────
+  const signer = new OracleSigner(mnemonic);
+  console.log("\n🔑 Oracle address  :", signer.getAddress());
+  console.log("📦 Oracle pubkey   :", signer.getPublicKeyBase64());
+  console.log("   (paste this into AlgoPayOracle.py create() call)\n");
+
+  // ── 2. Create client in anchor mode (no appId) ─────────────────────────
+  // Anchor mode: proof is stored in the note field of a 0-ALGO self-payment.
+  // Use this while testing before contract deployment.
+  const client = new AlgoPayClient({
+    mnemonic,
+    network: "testnet",
+    // appId: Number(process.env.ALGO_APP_ID),  // uncomment after deployment
+  });
+
+  // ── 3. Sign a payment proof ────────────────────────────────────────────
+  const proof = client.signer.sign({
+    payment_id: "demo_" + Date.now(),
+    amount:     100,
+    action:     "unlock",
+    currency:   "INR",
+  });
+
+  console.log("✍️  Signed proof:");
+  console.log(JSON.stringify(proof, null, 2));
+
+  // ── 4. Verify offline (no network) ────────────────────────────────────
+  const offchainResult = client.verifyProofOffchain(proof);
+  console.log("\n🔍 Off-chain verify:", offchainResult.valid ? "✅ valid" : "❌ " + offchainResult.reason);
+
+  // ── 5. Submit to Algorand ─────────────────────────────────────────────
+  console.log("\n⛓  Submitting to Algorand TestNet...");
+  const result = await client.verifyAndCommit({
+    payment_id: proof.payment_id,
+    amount:     proof.amount,
+    action:     proof.action,
+    currency:   proof.currency,
+  });
+
+  console.log("\n✅ Success!");
+  console.log("   txId        :", result.txId);
+  console.log("   Explorer    :", result.explorerUrl);
+  console.log("\n📋 APC-1 Credential:");
+  console.log(JSON.stringify(result.apc1, null, 2));
+}
+
+main().catch(e => { console.error("Error:", e.message); process.exit(1); });

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@algopayoracle/oracle-sdk",
-  "version": "1.0.1",
+  "version": "1.0.4",
   "description": "Programmable payment oracle SDK — bridge fiat payments to Algorand smart contracts",
   "main": "src/index.js",
   "files": [
     "src",
+    "examples",
     "README.md"
   ],
   "scripts": {

package/src/AlgoPayClient.js

@@ -86,7 +86,7 @@ class AlgoPayClient {
    * }>}
    */
   async verifyAndCommit({ payment_id, amount, action = "unlock", currency = "INR", provider = "unknown" }) {
-    const proof = this.signer.sign({ payment_id, amount, action, currency, provider }, this.appId);
+    const proof = this.signer.sign({ payment_id, amount, action, currency, provider }, this.appId || 0);
     const txId  = await this._submitProof(proof);
 
     return {