@carts1024/velo-sdk 0.1.0-alpha.1

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to the Velo SDK will be documented in this file.
+
+## [0.1.0-alpha.1] - 2026-07-01
+
+### Added
+
+- **Velo Client**: Class-based SDK client (`Velo`) with simple initialization: `new Velo({ apiKey })`.
+- **Checkout Sessions**: Creation of checkout links via `velo.checkout.sessions.create()`.
+- **Payment Intents**: Retrieve and list payment intents with cursor pagination support and project scoping.
+- **Webhook Verification**: Secure HMAC-SHA256 signature validation with clock skew/tolerance checking using `Velo.webhooks.verify()`.
+- **Typed Errors**: Custom error classes (`VeloAPIError`, `VeloAuthError`, `VeloRateLimitError`, `VeloValidationError`) matching API status codes.
+- **Idempotency**: Support for client-supplied `Idempotency-Key` headers on payment session creation.

package/README.md

@@ -0,0 +1,213 @@
+# Velo SDK for Node.js (Alpha)
+
+The official Velo SDK for Node.js and modern JavaScript environments.
+
+> [!NOTE]
+> This package is currently in **Alpha** (`0.1.0-alpha.1`) and is meant for server-side environments only.
+
+## Installation
+
+```bash
+npm install @velo/sdk
+# or
+pnpm add @velo/sdk
+# or
+yarn add @velo/sdk
+```
+
+## Getting Started
+
+Initialize the client with your Velo API key:
+
+```ts
+import { Velo } from "@velo/sdk";
+
+const velo = new Velo({
+  apiKey: process.env.VELO_API_KEY!,
+  environment: "testnet", // 'production', 'testnet', or 'development'
+});
+```
+
+### Creating a Checkout Session
+
+```ts
+const { checkoutUrl, paymentIntentId } = await velo.checkout.sessions.create({
+  amount: "10.00",
+  asset: "USDC",
+  description: "Order #1001",
+  successUrl: "https://yourdomain.com/success",
+  cancelUrl: "https://yourdomain.com/cancel",
+});
+
+// Redirect customer to the checkout URL
+```
+
+### Retrieving a Payment Intent
+
+```ts
+const paymentIntent = await velo.paymentIntents.retrieve("pi_12345");
+console.log(`Payment status: ${paymentIntent.status}`);
+```
+
+---
+
+## Webhook Verification
+
+Velo signs webhook events sent to your endpoints using HMAC-SHA256. Webhook verification is required to verify that incoming payloads are authentic and untampered.
+
+> [!IMPORTANT]
+> Webhook signature verification requires the **raw, unparsed request body**. Do not parse the request body as JSON prior to calling verify.
+>
+> Your webhook signing secret (`VELO_WEBHOOK_SECRET`) must remain **server-side only**. Never expose it to the browser.
+
+### Verification API
+
+You can verify signatures using the static `Velo.webhooks.verify` method or an instance-level `velo.webhooks.verify` method:
+
+```ts
+const event = await Velo.webhooks.verify({
+  payload: rawBody, // Raw string payload
+  signature: signatureHeader, // 'x-velo-signature' header value
+  secret: process.env.VELO_WEBHOOK_SECRET!, // Webhook signing secret
+  toleranceSeconds: 300, // Optional clock drift tolerance (default 5 minutes)
+});
+```
+
+`verify` will throw a `VeloWebhookSignatureVerificationError` (which extends `VeloValidationError`) if:
+
+- The signature is missing or malformed.
+- The timestamp is expired (older than `toleranceSeconds` or from the future).
+- The computed signature does not match the header.
+
+### Next.js App Router Example
+
+```ts
+import { NextResponse } from "next/server";
+import { Velo } from "@velo/sdk";
+
+export async function POST(request: Request) {
+  // 1. Get the raw text payload (DO NOT call request.json())
+  const payload = await request.text();
+
+  // 2. Get the signature header
+  const signature = request.headers.get("x-velo-signature");
+  const secret = process.env.VELO_WEBHOOK_SECRET!;
+
+  try {
+    // 3. Verify the signature
+    const event = await Velo.webhooks.verify({
+      payload,
+      signature,
+      secret,
+    });
+
+    // 4. Handle typed events
+    switch (event.type) {
+      case "payment.succeeded": {
+        const paymentIntent = event.paymentIntent;
+        console.log(`Payment succeeded for amount: ${paymentIntent.amount}`);
+        break;
+      }
+      case "payment.failed": {
+        console.log(`Payment failed: ${event.paymentIntent.id}`);
+        break;
+      }
+      case "payment_access.activated": {
+        console.log(`Project payment access activated!`);
+        break;
+      }
+      default:
+        console.log(`Unhandled event type: ${event.type}`);
+    }
+
+    return NextResponse.json({ received: true });
+  } catch (error) {
+    console.error("Signature verification failed:", error);
+    return new NextResponse("Webhook signature verification failed", { status: 400 });
+  }
+}
+```
+
+### Express.js Example
+
+Ensure you capture the raw body as a string. You can use `express.raw` middleware for this specific route.
+
+```ts
+import express from "express";
+import { Velo } from "@velo/sdk";
+
+const app = express();
+
+app.post("/webhooks", express.raw({ type: "application/json" }), async (req, res) => {
+  // 1. Get raw string payload
+  const payload = req.body.toString("utf8");
+
+  // 2. Get the signature header
+  const signature = req.headers["x-velo-signature"];
+  const secret = process.env.VELO_WEBHOOK_SECRET!;
+
+  try {
+    // 3. Verify signature
+    const event = await Velo.webhooks.verify({
+      payload,
+      signature: Array.isArray(signature) ? signature[0] : signature || null,
+      secret,
+    });
+
+    // 4. Handle events
+    if (event.type === "payment.succeeded") {
+      console.log(`Payment succeeded: ${event.paymentIntent.id}`);
+    }
+
+    res.status(200).send("OK");
+  } catch (error) {
+    console.error("Signature verification failed:", error);
+    res.status(400).send("Webhook signature verification failed");
+  }
+});
+```
+
+---
+
+## Environment Variables
+
+Configure the following environment variables in your server environments:
+
+| Variable              | Required          | Description                                                                                     |
+| --------------------- | ----------------- | ----------------------------------------------------------------------------------------------- |
+| `VELO_API_KEY`        | **Yes**           | Your Velo project API key (e.g. `tk_live_...` or `tk_test_...`).                                |
+| `VELO_WEBHOOK_SECRET` | Only for Webhooks | Used to verify signature of incoming webhook events.                                            |
+| `VELO_BASE_URL`       | No                | Overrides the default Velo API endpoint (defaults to `https://api.velo.xyz` or local dev base). |
+
+---
+
+## Idempotency
+
+To prevent double-charging or duplicate session creation due to network retries, pass an `idempotencyKey` in the `RequestOptions` object as the second parameter:
+
+```ts
+const session = await velo.checkout.sessions.create(
+  {
+    amount: "10.00",
+    asset: "USDC",
+    description: "Order #1001",
+  },
+  {
+    idempotencyKey: "unique-order-id-1001", // Prevents duplicates
+  },
+);
+```
+
+Idempotency keys are scoped to your project. Repeating a request with the same payload and same key will return the cached original response. Repeating with a different payload will throw a `VeloAPIError` with status code `409` (conflict).
+
+---
+
+## Testnet vs Mainnet & Alpha Limitations
+
+> [!WARNING]
+> This SDK is currently in **Alpha** (`0.1.0-alpha.1`) and subject to changes.
+>
+> - **Stellar Testnet Only**: During the alpha phase, all transactions and checkout sessions are routed through the Stellar Testnet. Mainnet is currently unsupported.
+> - **ESM-Only**: The package uses ESM exports and requires `"type": "module"` or an ESM-compatible bundler/environment. CommonJS `require()` is not supported directly.
+> - **Server-Side Only**: The SDK initializes and communicates using highly sensitive API keys and secrets. Do **NOT** use this SDK in browser environments or client-side code as it will leak your API credentials.
+> - **Browser Limitations**: Direct wallet connection, browser-based payment tracking, and front-end React components are excluded from the current alpha release.

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@carts1024/velo-sdk",
+  "version": "0.1.0-alpha.1",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "lint:fix": "oxlint --fix . && oxfmt --write . && tsc --noEmit",
+    "test": "node --experimental-strip-types --test src/*.test.ts"
+  },
+  "devDependencies": {
+    "@repo/typescript-config": "workspace:*",
+    "@types/node": "^22.15.3",
+    "typescript": "5.9.2"
+  }
+}

package/src/client.test.ts

@@ -0,0 +1,383 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { Velo } from "./client.ts";
+import { VeloAPIError, VeloAuthError, VeloRateLimitError, VeloValidationError } from "./errors.ts";
+import { HttpClient, resolveBaseUrl } from "./http.ts";
+
+test("Velo constructor validates apiKey", () => {
+  assert.throws(() => new Velo({ apiKey: "" }), /API key is required/);
+  assert.throws(() => new Velo({ apiKey: "   " }), /API key is required/);
+  assert.throws(() => new Velo({ apiKey: null as unknown as string }), /API key is required/);
+});
+
+test("resolveBaseUrl works as expected", () => {
+  assert.equal(
+    resolveBaseUrl({ apiKey: "key", baseUrl: "https://custom.velo.pay" }),
+    "https://custom.velo.pay",
+  );
+  assert.equal(
+    resolveBaseUrl({ apiKey: "key", environment: "production" }),
+    "https://api.velo.pay",
+  );
+  assert.equal(
+    resolveBaseUrl({ apiKey: "key", environment: "testnet" }),
+    "https://api.testnet.velo.pay",
+  );
+  assert.equal(
+    resolveBaseUrl({ apiKey: "key", environment: "development" }),
+    "http://localhost:3000",
+  );
+  assert.equal(resolveBaseUrl({ apiKey: "key" }), "http://localhost:3000");
+});
+
+test("HttpClient sets correct authorization and custom headers", async () => {
+  const originalFetch = globalThis.fetch;
+  let calledUrl = "";
+  let calledOptions: RequestInit | undefined;
+
+  globalThis.fetch = async (url, options) => {
+    calledUrl = url.toString();
+    calledOptions = options;
+    return new Response(JSON.stringify({ success: true }), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    });
+  };
+
+  try {
+    const client = new HttpClient({ apiKey: "test-key", baseUrl: "https://api.example.com" });
+    const res = await client.request(
+      "POST",
+      "/test",
+      { foo: "bar" },
+      { idempotencyKey: "idem-123" },
+    );
+
+    assert.deepEqual(res, { success: true });
+    assert.equal(calledUrl, "https://api.example.com/test");
+    assert.equal(calledOptions?.method, "POST");
+
+    const headers = calledOptions?.headers as Record<string, string>;
+    assert.equal(headers["Authorization"], "Bearer test-key");
+    assert.equal(headers["Content-Type"], "application/json");
+    assert.equal(headers["Idempotency-Key"], "idem-123");
+    assert.equal(calledOptions?.body, JSON.stringify({ foo: "bar" }));
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("HttpClient timeout behavior throws error", async () => {
+  const originalFetch = globalThis.fetch;
+
+  globalThis.fetch = async (url, options) => {
+    const signal = options?.signal;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        resolve(new Response(JSON.stringify({}), { status: 200 }));
+      }, 100);
+
+      if (signal) {
+        if (signal.aborted) {
+          clearTimeout(timer);
+          reject(new DOMException("The operation was aborted.", "AbortError"));
+          return;
+        }
+        signal.addEventListener("abort", () => {
+          clearTimeout(timer);
+          reject(new DOMException("The operation was aborted.", "AbortError"));
+        });
+      }
+    });
+  };
+
+  try {
+    const client = new HttpClient({ apiKey: "test-key", timeoutMs: 10 });
+    await assert.rejects(
+      () => client.request("GET", "/test"),
+      (err: unknown) => {
+        assert.equal(err instanceof VeloAPIError, true);
+        const error = err as VeloAPIError;
+        assert.equal(error.status, 408);
+        assert.match(error.message, /timed out/);
+        return true;
+      },
+    );
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("HttpClient maps REST error responses correctly", async () => {
+  const originalFetch = globalThis.fetch;
+
+  const mockErrorResponse = (
+    status: number,
+    type: string,
+    message: string,
+    code: string,
+    param?: string,
+  ) => {
+    return async () => {
+      const responseBody = JSON.stringify({
+        error: { type, message, code, param },
+      });
+      return new Response(responseBody, {
+        status,
+        headers: {
+          "Content-Type": "application/json",
+          "x-request-id": "req-id-123",
+        },
+      });
+    };
+  };
+
+  try {
+    const client = new HttpClient({ apiKey: "test-key" });
+
+    // 401 Unauthorized -> VeloAuthError
+    globalThis.fetch = mockErrorResponse(401, "auth_error", "Invalid API key", "invalid_api_key");
+    await assert.rejects(
+      () => client.request("GET", "/test"),
+      (err: unknown) => {
+        assert.equal(err instanceof VeloAuthError, true);
+        const error = err as VeloAuthError;
+        assert.equal(error.status, 401);
+        assert.equal(error.code, "invalid_api_key");
+        assert.equal(error.requestId, "req-id-123");
+        return true;
+      },
+    );
+
+    // 400 Bad Request -> VeloValidationError
+    globalThis.fetch = mockErrorResponse(
+      400,
+      "validation_error",
+      "Invalid amount",
+      "invalid_request",
+      "amount",
+    );
+    await assert.rejects(
+      () => client.request("GET", "/test"),
+      (err: unknown) => {
+        assert.equal(err instanceof VeloValidationError, true);
+        const error = err as VeloValidationError;
+        assert.equal(error.status, 400);
+        assert.equal(error.code, "invalid_request");
+        assert.equal(error.param, "amount");
+        assert.equal(error.requestId, "req-id-123");
+        return true;
+      },
+    );
+
+    // 429 Too Many Requests -> VeloRateLimitError
+    globalThis.fetch = mockErrorResponse(
+      429,
+      "rate_limit_error",
+      "Rate limit exceeded",
+      "rate_limit_exceeded",
+    );
+    await assert.rejects(
+      () => client.request("GET", "/test"),
+      (err: unknown) => {
+        assert.equal(err instanceof VeloRateLimitError, true);
+        const error = err as VeloRateLimitError;
+        assert.equal(error.status, 429);
+        assert.equal(error.code, "rate_limit_exceeded");
+        assert.equal(error.requestId, "req-id-123");
+        return true;
+      },
+    );
+
+    // 500 Internal Error -> VeloAPIError
+    globalThis.fetch = mockErrorResponse(500, "api_error", "Internal error", "internal_error");
+    await assert.rejects(
+      () => client.request("GET", "/test"),
+      (err: unknown) => {
+        assert.equal(err instanceof VeloAPIError, true);
+        const error = err as VeloAPIError;
+        assert.equal(error.status, 500);
+        assert.equal(error.code, "internal_error");
+        assert.equal(error.requestId, "req-id-123");
+        return true;
+      },
+    );
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("Velo checkout.sessions.create and paymentIntents.create construct correct requests", async () => {
+  const originalFetch = globalThis.fetch;
+  let calledUrl = "";
+  let calledOptions: RequestInit | undefined;
+
+  globalThis.fetch = async (url, options) => {
+    calledUrl = url.toString();
+    calledOptions = options;
+    return new Response(JSON.stringify({ id: "pi_123", object: "payment_intent" }), {
+      status: 201,
+      headers: { "Content-Type": "application/json" },
+    });
+  };
+
+  try {
+    const velo = new Velo({ apiKey: "test-key", baseUrl: "https://api.example.com" });
+    const res1 = await velo.checkout.sessions.create({ amount: "10.00", asset: "USDC" });
+    assert.deepEqual(res1, { id: "pi_123", object: "payment_intent" });
+    assert.equal(calledUrl, "https://api.example.com/api/v1/payment-intents");
+    assert.equal(calledOptions?.method, "POST");
+    assert.equal(calledOptions?.body, JSON.stringify({ amount: "10.00", asset: "USDC" }));
+
+    const res2 = await velo.paymentIntents.create({ amount: "20.00", asset: "USDC" });
+    assert.deepEqual(res2, { id: "pi_123", object: "payment_intent" });
+    assert.equal(calledUrl, "https://api.example.com/api/v1/payment-intents");
+    assert.equal(calledOptions?.method, "POST");
+    assert.equal(calledOptions?.body, JSON.stringify({ amount: "20.00", asset: "USDC" }));
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("Velo paymentIntents.retrieve retrieves payment intent by id with encoding", async () => {
+  const originalFetch = globalThis.fetch;
+  let calledUrl = "";
+
+  globalThis.fetch = async (url) => {
+    calledUrl = url.toString();
+    return new Response(JSON.stringify({ id: "pi_123", object: "payment_intent" }), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    });
+  };
+
+  try {
+    const velo = new Velo({ apiKey: "test-key", baseUrl: "https://api.example.com" });
+    const res = await velo.paymentIntents.retrieve("pi/123");
+    assert.deepEqual(res, { id: "pi_123", object: "payment_intent" });
+    assert.equal(calledUrl, "https://api.example.com/api/v1/payment-intents/pi%2F123");
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("Velo paymentIntents.retrieve validates that ID is present", async () => {
+  const velo = new Velo({ apiKey: "test-key" });
+  await assert.rejects(() => velo.paymentIntents.retrieve(""), /Payment intent ID is required/);
+  await assert.rejects(() => velo.paymentIntents.retrieve("   "), /Payment intent ID is required/);
+});
+
+test("Velo paymentIntents.list parses query parameters correctly", async () => {
+  const originalFetch = globalThis.fetch;
+  let calledUrl = "";
+
+  globalThis.fetch = async (url) => {
+    calledUrl = url.toString();
+    return new Response(
+      JSON.stringify({ object: "list", data: [], hasMore: false, nextCursor: null }),
+      {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      },
+    );
+  };
+
+  try {
+    const velo = new Velo({ apiKey: "test-key", baseUrl: "https://api.example.com" });
+    const res = await velo.paymentIntents.list({ status: "paid", limit: 50, cursor: "abc" });
+    assert.deepEqual(res, { object: "list", data: [], hasMore: false, nextCursor: null });
+    assert.equal(
+      calledUrl,
+      "https://api.example.com/api/v1/payment-intents?status=paid&limit=50&cursor=abc",
+    );
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("GET request retries on 500 then succeeds", async () => {
+  const originalFetch = globalThis.fetch;
+  let calls = 0;
+
+  globalThis.fetch = async (_url, _options) => {
+    calls++;
+    if (calls === 1) {
+      return new Response(
+        JSON.stringify({ error: { type: "api_error", message: "Server error", code: "internal" } }),
+        { status: 500, headers: { "Content-Type": "application/json" } },
+      );
+    }
+    return new Response(JSON.stringify({ id: "pi_123", object: "payment_intent" }), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    });
+  };
+
+  try {
+    const velo = new Velo({ apiKey: "test-key", baseUrl: "https://api.example.com" });
+    const res = await velo.paymentIntents.retrieve("pi_123");
+    assert.deepEqual(res, { id: "pi_123", object: "payment_intent" });
+    assert.equal(calls, 2);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("POST without idempotency key does not retry on 500", async () => {
+  const originalFetch = globalThis.fetch;
+  let calls = 0;
+
+  globalThis.fetch = async (_url, _options) => {
+    calls++;
+    return new Response(
+      JSON.stringify({ error: { type: "api_error", message: "Server error", code: "internal" } }),
+      { status: 500, headers: { "Content-Type": "application/json" } },
+    );
+  };
+
+  try {
+    const velo = new Velo({ apiKey: "test-key", baseUrl: "https://api.example.com" });
+    await assert.rejects(
+      () => velo.checkout.sessions.create({ amount: "10.00" }),
+      (err: unknown) => {
+        assert.equal(err instanceof VeloAPIError, true);
+        return true;
+      },
+    );
+    assert.equal(calls, 1);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("POST with idempotency key retries on 500", async () => {
+  const originalFetch = globalThis.fetch;
+  let calls = 0;
+
+  globalThis.fetch = async (_url, _options) => {
+    calls++;
+    if (calls === 1) {
+      return new Response(
+        JSON.stringify({ error: { type: "api_error", message: "Server error", code: "internal" } }),
+        { status: 500, headers: { "Content-Type": "application/json" } },
+      );
+    }
+    return new Response(JSON.stringify({ id: "pi_123", object: "payment_intent" }), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    });
+  };
+
+  try {
+    const velo = new Velo({ apiKey: "test-key", baseUrl: "https://api.example.com" });
+    const res = await velo.checkout.sessions.create(
+      { amount: "10.00" },
+      { idempotencyKey: "idem-1" },
+    );
+    assert.deepEqual(res, { id: "pi_123", object: "payment_intent" });
+    assert.equal(calls, 2);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});