@carts1024/velo-sdk 0.1.0-alpha.1

package/src/client.ts

@@ -0,0 +1,93 @@
+import type {
+  VeloConfig,
+  CreateCheckoutSessionParams,
+  RequestOptions,
+  PaymentIntent,
+  ListPaymentIntentsQuery,
+  ListResponse,
+  WebhookEvent,
+  VerifyWebhookParams,
+} from "./types.ts";
+
+import { HttpClient } from "./http.ts";
+import { verifyWebhookSignature } from "./webhooks.ts";
+
+export class Velo {
+  private readonly http: HttpClient;
+
+  static readonly webhooks = {
+    verify: async (params: VerifyWebhookParams): Promise<WebhookEvent> => {
+      return verifyWebhookSignature(params);
+    },
+  };
+
+  readonly webhooks = {
+    verify: async (params: VerifyWebhookParams): Promise<WebhookEvent> => {
+      return verifyWebhookSignature(params);
+    },
+  };
+
+  constructor(config: VeloConfig) {
+    if (
+      !config ||
+      !config.apiKey ||
+      typeof config.apiKey !== "string" ||
+      config.apiKey.trim() === ""
+    ) {
+      throw new Error("API key is required");
+    }
+    this.http = new HttpClient(config);
+  }
+
+  readonly checkout = {
+    sessions: {
+      create: async (
+        params: CreateCheckoutSessionParams,
+        options?: RequestOptions,
+      ): Promise<PaymentIntent> => {
+        return this.http.request<PaymentIntent>("POST", "/api/v1/payment-intents", params, options);
+      },
+    },
+  };
+
+  readonly paymentIntents = {
+    create: async (
+      params: CreateCheckoutSessionParams,
+      options?: RequestOptions,
+    ): Promise<PaymentIntent> => {
+      return this.http.request<PaymentIntent>("POST", "/api/v1/payment-intents", params, options);
+    },
+    retrieve: async (id: string, options?: RequestOptions): Promise<PaymentIntent> => {
+      if (!id || typeof id !== "string" || id.trim() === "") {
+        throw new Error("Payment intent ID is required");
+      }
+      return this.http.request<PaymentIntent>(
+        "GET",
+        `/api/v1/payment-intents/${encodeURIComponent(id)}`,
+        undefined,
+        options,
+      );
+    },
+    list: async (
+      query?: ListPaymentIntentsQuery,
+      options?: RequestOptions,
+    ): Promise<ListResponse<PaymentIntent>> => {
+      let path = "/api/v1/payment-intents";
+      const searchParams = new URLSearchParams();
+      if (query?.status) {
+        searchParams.append("status", query.status);
+      }
+      if (query?.limit !== undefined) {
+        searchParams.append("limit", String(query.limit));
+      }
+      if (query?.cursor) {
+        searchParams.append("cursor", query.cursor);
+      }
+      const queryString = searchParams.toString();
+      if (queryString) {
+        path += `?${queryString}`;
+      }
+      return this.http.request<ListResponse<PaymentIntent>>("GET", path, undefined, options);
+    },
+  };
+}

package/src/errors.ts

@@ -0,0 +1,95 @@
+export class VeloError extends Error {
+  readonly status?: number;
+  readonly code?: string;
+  readonly param?: string;
+  readonly requestId?: string;
+
+  constructor(
+    message: string,
+    options?: { status?: number; code?: string; param?: string; requestId?: string },
+  ) {
+    super(message);
+    this.name = this.constructor.name;
+    this.status = options?.status;
+    this.code = options?.code;
+    this.param = options?.param;
+    this.requestId = options?.requestId;
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+}
+
+export class VeloAuthError extends VeloError {
+  constructor(message: string, options?: { status?: number; code?: string; requestId?: string }) {
+    super(message, options);
+  }
+}
+
+export class VeloValidationError extends VeloError {
+  constructor(
+    message: string,
+    options?: { status?: number; code?: string; param?: string; requestId?: string },
+  ) {
+    super(message, options);
+  }
+}
+
+export class VeloRateLimitError extends VeloError {
+  constructor(message: string, options?: { status?: number; code?: string; requestId?: string }) {
+    super(message, options);
+  }
+}
+
+export class VeloAPIError extends VeloError {
+  constructor(message: string, options?: { status?: number; code?: string; requestId?: string }) {
+    super(message, options);
+  }
+}
+
+export class VeloWebhookSignatureVerificationError extends VeloValidationError {
+  constructor(message: string) {
+    super(message, { status: 400, code: "webhook_signature_verification_failed" });
+  }
+}
+
+export function mapErrorResponse(status: number, payload: unknown, requestId?: string): VeloError {
+  const errorObj =
+    payload &&
+    typeof payload === "object" &&
+    "error" in payload &&
+    payload.error &&
+    typeof payload.error === "object"
+      ? (payload.error as Record<string, unknown>)
+      : {};
+  const message =
+    typeof errorObj.message === "string"
+      ? errorObj.message
+      : `Request failed with status ${status}`;
+  const code = typeof errorObj.code === "string" ? errorObj.code : undefined;
+  const param = typeof errorObj.param === "string" ? errorObj.param : undefined;
+  const reqId = typeof errorObj.requestId === "string" ? errorObj.requestId : requestId;
+  const errorType = typeof errorObj.type === "string" ? errorObj.type : undefined;
+
+  const options = { status, code, param, requestId: reqId };
+
+  if (status === 401 || errorType === "auth_error") {
+    return new VeloAuthError(message, options);
+  }
+  if (status === 429 || errorType === "rate_limit_error") {
+    return new VeloRateLimitError(message, options);
+  }
+  if (
+    status === 400 ||
+    status === 404 ||
+    status === 409 ||
+    errorType === "validation_error" ||
+    errorType === "not_found_error" ||
+    errorType === "idempotency_error"
+  ) {
+    return new VeloValidationError(message, options);
+  }
+
+  return new VeloAPIError(message, options);
+}

package/src/http.ts

@@ -0,0 +1,123 @@
+import type { VeloConfig, RequestOptions } from "./types.ts";
+
+import { mapErrorResponse, VeloAPIError, VeloRateLimitError } from "./errors.ts";
+
+export function resolveBaseUrl(config: VeloConfig): string {
+  if (config.baseUrl) {
+    return config.baseUrl;
+  }
+  const env = config.environment;
+  if (env === "production") {
+    return "https://api.velo.pay";
+  }
+  if (env === "testnet") {
+    return "https://api.testnet.velo.pay";
+  }
+  return "http://localhost:3000";
+}
+
+export class HttpClient {
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+  private readonly timeoutMs: number;
+
+  constructor(config: VeloConfig) {
+    this.apiKey = config.apiKey;
+    this.baseUrl = resolveBaseUrl(config);
+    this.timeoutMs = config.timeoutMs ?? 30000;
+  }
+
+  async request<T>(
+    method: "GET" | "POST" | "PUT" | "DELETE",
+    path: string,
+    body?: unknown,
+    options?: RequestOptions,
+  ): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json",
+    };
+
+    if (options?.idempotencyKey) {
+      headers["Idempotency-Key"] = options.idempotencyKey;
+    }
+
+    const maxRetries = 2;
+    let attempt = 0;
+
+    while (true) {
+      attempt++;
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => {
+        controller.abort();
+      }, this.timeoutMs);
+
+      try {
+        const response = await fetch(url, {
+          method,
+          headers,
+          body: body ? JSON.stringify(body) : undefined,
+          signal: controller.signal,
+        });
+
+        const requestId = response.headers.get("x-request-id") || undefined;
+
+        let payload: unknown;
+        const contentType = response.headers.get("content-type") || "";
+        if (contentType.includes("application/json")) {
+          const text = await response.text();
+          try {
+            payload = JSON.parse(text);
+          } catch {
+            payload = text;
+          }
+        } else {
+          payload = await response.text();
+        }
+
+        if (!response.ok) {
+          throw mapErrorResponse(response.status, payload, requestId);
+        }
+
+        return payload as T;
+      } catch (err) {
+        if (
+          err instanceof Error &&
+          (err.name === "AbortError" || (err instanceof DOMException && err.name === "AbortError"))
+        ) {
+          throw new VeloAPIError(`Request timed out after ${this.timeoutMs}ms`, {
+            status: 408,
+            code: "timeout",
+          });
+        }
+
+        // Network failures in fetch throw TypeError
+        const isNetworkError =
+          err instanceof TypeError ||
+          (err instanceof Error &&
+            (err.message.includes("fetch failed") ||
+              err.message.includes("ECONNREFUSED") ||
+              err.message.includes("ENOTFOUND") ||
+              err.message.includes("network error")));
+
+        const isRetryableError =
+          err instanceof VeloRateLimitError ||
+          (err instanceof VeloAPIError && err.status !== undefined && err.status >= 500) ||
+          isNetworkError;
+
+        const canRetryMethod = method === "GET" || (method === "POST" && !!options?.idempotencyKey);
+
+        if (isRetryableError && canRetryMethod && attempt <= maxRetries) {
+          const delay = 500 * Math.pow(2, attempt - 1);
+          await new Promise((resolve) => setTimeout(resolve, delay));
+          continue;
+        }
+
+        throw err;
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./types.ts";
+export * from "./errors.ts";
+export * from "./client.ts";
+export * from "./webhooks.ts";

package/src/testnet-flow.ts

@@ -0,0 +1,152 @@
+import { execSync } from "child_process";
+import crypto from "crypto";
+
+import { Velo } from "./client.ts";
+
+const PROJECT_ID = "j97102bbzrfdaabs3s05g1624h89k054";
+
+async function run() {
+  console.log("🚀 Starting Velo SDK E2E local verification flow...");
+
+  // 1. Generate a temporary API Key using Convex CLI
+  console.log("Generating a temporary API key for project demopay...");
+  const rawOutput = execSync(
+    `npx convex run projects/mutation:generateApiKeyInternal '{"id": "${PROJECT_ID}", "label": "E2E SDK Test"}'`,
+    { cwd: "../../apps/web", encoding: "utf8" },
+  );
+
+  // Extract token using regex matching tk_live_[a-f0-9]{32}
+  const match = rawOutput.match(/tk_live_[a-f0-9]{32}/);
+  if (!match) {
+    throw new Error(`Failed to extract API key from output: ${rawOutput}`);
+  }
+  const apiKey = match[0];
+  console.log(`Generated API Key: ${apiKey.slice(0, 12)}...`);
+
+  // 2. Initialize Velo client
+  const velo = new Velo({
+    apiKey,
+    environment: "testnet",
+    baseUrl: "http://localhost:3000",
+  });
+
+  // 3. Create a checkout session
+  console.log("Creating checkout session...");
+  const session = await velo.checkout.sessions.create({
+    amount: "10.00",
+    asset: "USDC",
+    description: "SDK Verification Order #1001",
+    successUrl: "http://localhost:3000/pay/success",
+    cancelUrl: "http://localhost:3000/pay/cancel",
+  });
+
+  console.log("Checkout session created successfully:");
+  console.log(`- ID: ${session.id}`);
+  console.log(`- Status: ${session.status}`);
+  console.log(`- Checkout URL: ${session.checkoutUrl}`);
+
+  if (!session.checkoutUrl || !session.checkoutUrl.startsWith("http://localhost:3000/pay/")) {
+    throw new Error("Invalid checkout URL format");
+  }
+
+  // 4. Retrieve the payment intent using the SDK
+  console.log(`Retrieving payment intent ${session.id}...`);
+  const retrieved = await velo.paymentIntents.retrieve(session.id);
+  console.log(`Retrieved status: ${retrieved.status}`);
+  if (retrieved.status !== "created") {
+    throw new Error(`Expected status to be 'created', got: ${retrieved.status}`);
+  }
+
+  // 5. Transition to pending using Convex CLI
+  console.log("Simulating customer opening the checkout (transition to pending)...");
+  execSync(
+    `npx convex run payment_intents/mutations:updateStatus '{"paymentIntentId": "${session.id}", "status": "pending"}'`,
+    { cwd: "../../apps/web" },
+  );
+
+  const pendingRetrieved = await velo.paymentIntents.retrieve(session.id);
+  console.log(`Retrieved status after opening checkout: ${pendingRetrieved.status}`);
+  if (pendingRetrieved.status !== "pending") {
+    throw new Error(`Expected status to be 'pending', got: ${pendingRetrieved.status}`);
+  }
+
+  // 6. Transition to paid using Convex CLI (simulates ledger verification success)
+  console.log("Simulating on-chain payment success (transition to paid)...");
+  execSync(
+    `npx convex run payment_intents/mutations:markVerifiedPaid '{"paymentIntentId": "${session.id}", "txHash": "c8731ea2a4fd43d0221b4c0eb5687c098e6bfcb6a58dbb4d01d698a0a8064cd9"}'`,
+    { cwd: "../../apps/web" },
+  );
+
+  const paidRetrieved = await velo.paymentIntents.retrieve(session.id);
+  console.log(`Retrieved status after payment verified: ${paidRetrieved.status}`);
+  if (paidRetrieved.status !== "paid") {
+    throw new Error(`Expected status to be 'paid', got: ${paidRetrieved.status}`);
+  }
+
+  // 7. Verify listing payment intents
+  console.log("Listing payment intents...");
+  const list = await velo.paymentIntents.list({ limit: 5 });
+  console.log(`Found ${list.data.length} payment intents in list.`);
+  const found = list.data.some((item) => item.id === session.id);
+  if (!found) {
+    throw new Error("Created session not found in list response");
+  }
+
+  // 8. Simulate webhook verification
+  console.log("Simulating and verifying webhook signature...");
+  const secret = "whsec_48d83b56a6ffd001b6cb3a75975a9254";
+  const payloadObj = {
+    id: crypto.randomUUID(),
+    type: "payment.succeeded",
+    test: true,
+    sentAt: new Date().toISOString(),
+    project: {
+      id: PROJECT_ID,
+      name: "DemoPay",
+      slug: "demopay",
+    },
+    paymentIntent: {
+      id: session.id,
+      amount: "10.00",
+      asset: "USDC",
+      status: "paid",
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    },
+  };
+
+  const payload = JSON.stringify(payloadObj);
+  const timestamp = Math.floor(Date.now() / 1000);
+  const signaturePayload = `${timestamp}.${payload}`;
+  const hmac = crypto.createHmac("sha256", secret);
+  hmac.update(signaturePayload);
+  const hash = hmac.digest("hex");
+  const signatureHeader = `t=${timestamp},v1=${hash}`;
+
+  const verifiedEvent = await Velo.webhooks.verify({
+    payload,
+    signature: signatureHeader,
+    secret,
+  });
+
+  if (verifiedEvent.type === "payment.succeeded") {
+    console.log("Webhook verified successfully:");
+    console.log(`- Event ID: ${verifiedEvent.id}`);
+    console.log(`- Event Type: ${verifiedEvent.type}`);
+    console.log(`- Payment Intent ID: ${verifiedEvent.paymentIntent.id}`);
+    console.log(`- Payment Intent Status: ${verifiedEvent.paymentIntent.status}`);
+
+    if (verifiedEvent.paymentIntent.status !== "paid") {
+      throw new Error("Webhook verification returned incorrect status");
+    }
+  } else {
+    throw new Error(`Expected payment.succeeded event, got: ${verifiedEvent.type}`);
+  }
+
+  console.log("🎉 Velo SDK local e2e integration flow completed successfully!");
+}
+
+run().catch((err) => {
+  console.error("❌ E2E verification failed:", err);
+  process.exit(1);
+});

package/src/types.ts

@@ -0,0 +1,123 @@
+export type PaymentIntentStatus =
+  | "created"
+  | "pending"
+  | "paid"
+  | "failed"
+  | "expired"
+  | "cancelled";
+
+export type PaymentIntent = {
+  id: string;
+  object: "payment_intent";
+  paymentIntentId: string;
+  status: PaymentIntentStatus;
+  amount: string;
+  asset: string;
+  description: string | null;
+  checkoutUrl: string | null;
+  successUrl: string | null;
+  cancelUrl: string | null;
+  expiresAt: string;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type VeloConfig = {
+  apiKey: string;
+  baseUrl?: string;
+  environment?: "production" | "testnet" | "development" | string;
+  timeoutMs?: number;
+};
+
+export type CreateCheckoutSessionParams = {
+  amount: string;
+  asset?: string;
+  description?: string;
+  successUrl?: string;
+  cancelUrl?: string;
+};
+
+export type RequestOptions = {
+  idempotencyKey?: string;
+};
+
+export type ListPaymentIntentsQuery = {
+  status?: PaymentIntentStatus;
+  limit?: number;
+  cursor?: string;
+};
+
+export type ListResponse<T> = {
+  object: "list";
+  data: T[];
+  hasMore: boolean;
+  nextCursor: string | null;
+};
+
+export type WebhookEventType =
+  | "payment.created"
+  | "payment.succeeded"
+  | "payment.failed"
+  | "payment_access.activated"
+  | "payment.access_activated"
+  | "contract.event";
+
+export type WebhookEventBase = {
+  id: string;
+  type: WebhookEventType;
+  test: boolean;
+  sentAt: string;
+  project: {
+    id: string;
+    registryProjectId: string;
+    name: string;
+    slug: string;
+  };
+};
+
+export type WebhookPaymentIntentData = {
+  id: string;
+  amount: string;
+  asset: string;
+  receiverAddress: string;
+  merchantName: string;
+  description: string | null;
+  status: PaymentIntentStatus;
+  payerAddress?: string;
+  txHash?: string;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type WebhookPaymentEvent = WebhookEventBase & {
+  type:
+    | "payment.created"
+    | "payment.succeeded"
+    | "payment.failed"
+    | "payment_access.activated"
+    | "payment.access_activated";
+  paymentIntent: WebhookPaymentIntentData;
+};
+
+export type WebhookContractEvent = WebhookEventBase & {
+  type: "contract.event";
+  contractId: string;
+  transactionHash: string;
+  ledger: number;
+  event: {
+    id: string;
+    topic: string;
+    type: string;
+    data: unknown;
+    observedAt: string;
+  };
+};
+
+export type WebhookEvent = WebhookPaymentEvent | WebhookContractEvent;
+
+export type VerifyWebhookParams = {
+  payload: string;
+  signature: string | null;
+  secret: string;
+  toleranceSeconds?: number;
+};