@b3dotfun/sdk 0.1.68-alpha.2 → 0.1.68-alpha.4

package/src/anyspend/platform/client.ts

@@ -0,0 +1,198 @@
+/**
+ * Core HTTP client for the AnySpend Platform API.
+ * Handles authentication, retries, error parsing, and idempotency.
+ */
+
+import { parseApiError, type ApiErrorResponse } from "./errors";
+import { generateIdempotencyKey } from "./utils/idempotency";
+
+export interface ClientConfig {
+  baseUrl?: string;
+  timeout?: number;
+  maxRetries?: number;
+  idempotencyKeyGenerator?: () => string;
+}
+
+export const DEFAULT_BASE_URL = "https://platform-api.anyspend.com/api/v1";
+const DEFAULT_TIMEOUT = 30000;
+const DEFAULT_MAX_RETRIES = 3;
+
+export class HttpClient {
+  private apiKey: string;
+  private baseUrl: string;
+  private timeout: number;
+  private maxRetries: number;
+  private generateIdempotencyKey: () => string;
+
+  constructor(apiKey: string, config: ClientConfig = {}) {
+    this.apiKey = apiKey;
+    this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeout = config.timeout || DEFAULT_TIMEOUT;
+    this.maxRetries = config.maxRetries || DEFAULT_MAX_RETRIES;
+    this.generateIdempotencyKey = config.idempotencyKeyGenerator || generateIdempotencyKey;
+  }
+
+  async get<T>(path: string, params?: object): Promise<T> {
+    const url = this.buildUrl(path, params);
+    return this.request<T>("GET", url);
+  }
+
+  async post<T>(path: string, body?: object): Promise<T> {
+    const url = this.buildUrl(path);
+    return this.request<T>("POST", url, body);
+  }
+
+  async patch<T>(path: string, body: object): Promise<T> {
+    const url = this.buildUrl(path);
+    return this.request<T>("PATCH", url, body);
+  }
+
+  async delete<T>(path: string, body?: object): Promise<T> {
+    const url = this.buildUrl(path);
+    return this.request<T>("DELETE", url, body);
+  }
+
+  async postFormData<T>(path: string, formData: FormData): Promise<T> {
+    const url = this.buildUrl(path);
+    return this.requestRaw<T>("POST", url, formData);
+  }
+
+  private buildUrl(path: string, params?: object): string {
+    const url = new URL(`${this.baseUrl}${path}`);
+    if (params) {
+      for (const [key, value] of Object.entries(params as Record<string, unknown>)) {
+        if (value !== undefined && value !== null) url.searchParams.set(key, String(value));
+      }
+    }
+    return url.toString();
+  }
+
+  private async request<T>(method: string, url: string, body?: object): Promise<T> {
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json",
+    };
+
+    // Auto-generate idempotency key for POST/PATCH
+    if (method === "POST" || method === "PATCH") {
+      headers["Idempotency-Key"] = this.generateIdempotencyKey();
+    }
+
+    return this.executeWithRetry<T>(method, url, headers, body ? JSON.stringify(body) : undefined);
+  }
+
+  private async requestRaw<T>(method: string, url: string, body: FormData): Promise<T> {
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${this.apiKey}`,
+    };
+
+    return this.executeWithRetry<T>(method, url, headers, body);
+  }
+
+  private async executeWithRetry<T>(
+    method: string,
+    url: string,
+    headers: Record<string, string>,
+    body?: string | FormData,
+  ): Promise<T> {
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+        const response = await fetch(url, {
+          method,
+          headers,
+          body,
+          signal: controller.signal,
+        });
+
+        clearTimeout(timeoutId);
+
+        if (response.ok) {
+          // Handle CSV/text responses
+          const contentType = response.headers.get("Content-Type") || "";
+          if (contentType.includes("text/csv")) {
+            return (await response.text()) as unknown as T;
+          }
+          return (await response.json()) as T;
+        }
+
+        // Parse error response
+        const errorBody = (await response.json().catch(() => ({
+          error: { type: "api_error", code: "internal_error", message: "Unknown error" },
+        }))) as ApiErrorResponse;
+
+        const error = parseApiError(response.status, errorBody, response.headers);
+
+        // Don't retry 4xx errors (except 429 rate limits)
+        if (response.status < 500 && response.status !== 429) {
+          throw error;
+        }
+
+        // For 429, wait the specified retry-after time
+        if (response.status === 429) {
+          const retryAfter = parseInt(response.headers.get("Retry-After") || "1", 10);
+          await this.sleep(retryAfter * 1000);
+          lastError = error;
+          continue;
+        }
+
+        // For 5xx, retry with exponential backoff
+        lastError = error;
+        if (attempt < this.maxRetries) {
+          await this.sleep(Math.pow(2, attempt) * 1000);
+        }
+      } catch (err) {
+        if (err instanceof Error && err.name === "AbortError") {
+          lastError = new Error(`Request timed out after ${this.timeout}ms`);
+        } else if (err instanceof Error && "type" in err) {
+          // Already a parsed ApiError, re-throw
+          throw err;
+        } else {
+          lastError = err instanceof Error ? err : new Error(String(err));
+        }
+
+        if (attempt < this.maxRetries) {
+          await this.sleep(Math.pow(2, attempt) * 1000);
+        }
+      }
+    }
+
+    throw lastError || new Error("Request failed after retries");
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}
+
+/**
+ * Static HTTP client for unauthenticated requests (quick-pay).
+ */
+export class StaticHttpClient {
+  static async post<T>(baseUrl: string, path: string, body: Record<string, unknown>): Promise<T> {
+    const url = `${baseUrl.replace(/\/$/, "")}${path}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT);
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+    clearTimeout(timeoutId);
+
+    if (response.ok) {
+      return (await response.json()) as T;
+    }
+
+    const errorBody = (await response.json().catch(() => ({
+      error: { type: "api_error", code: "internal_error", message: "Unknown error" },
+    }))) as ApiErrorResponse;
+
+    throw parseApiError(response.status, errorBody, response.headers);
+  }
+}

package/src/anyspend/platform/errors.ts

@@ -0,0 +1,92 @@
+/**
+ * Typed error classes for the AnySpend Platform API client.
+ */
+
+export interface ApiErrorResponse {
+  error: {
+    type: string;
+    code: string;
+    message: string;
+    param?: string;
+  };
+}
+
+export class ApiError extends Error {
+  readonly type: string;
+  readonly code: string;
+  readonly status: number;
+  readonly param?: string;
+
+  constructor(status: number, body: ApiErrorResponse) {
+    super(body.error.message);
+    this.name = "ApiError";
+    this.type = body.error.type;
+    this.code = body.error.code;
+    this.status = status;
+    this.param = body.error.param;
+  }
+}
+
+export class AuthenticationError extends ApiError {
+  constructor(status: number, body: ApiErrorResponse) {
+    super(status, body);
+    this.name = "AuthenticationError";
+  }
+}
+
+export class PermissionError extends ApiError {
+  constructor(status: number, body: ApiErrorResponse) {
+    super(status, body);
+    this.name = "PermissionError";
+  }
+}
+
+export class RateLimitError extends ApiError {
+  readonly retryAfter: number;
+
+  constructor(status: number, body: ApiErrorResponse, retryAfter: number) {
+    super(status, body);
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+  }
+}
+
+export class NotFoundError extends ApiError {
+  constructor(status: number, body: ApiErrorResponse) {
+    super(status, body);
+    this.name = "NotFoundError";
+  }
+}
+
+export class IdempotencyError extends ApiError {
+  constructor(status: number, body: ApiErrorResponse) {
+    super(status, body);
+    this.name = "IdempotencyError";
+  }
+}
+
+/**
+ * Parse an API error response into the appropriate typed error class.
+ */
+export function parseApiError(status: number, body: ApiErrorResponse, headers?: Headers): ApiError {
+  const type = body.error?.type;
+
+  if (status === 401 || type === "authentication_error") {
+    return new AuthenticationError(status, body);
+  }
+  if (status === 403 || type === "permission_error") {
+    return new PermissionError(status, body);
+  }
+  if (status === 429 || type === "rate_limit_error") {
+    const retryAfter = parseInt(headers?.get("Retry-After") || "60", 10);
+    return new RateLimitError(status, body, retryAfter);
+  }
+  if (status === 404 || type === "not_found_error") {
+    return new NotFoundError(status, body);
+  }
+  if (type === "idempotency_error") {
+    return new IdempotencyError(status, body);
+  }
+
+  return new ApiError(status, body);
+}

package/src/anyspend/platform/index.ts

@@ -0,0 +1,129 @@
+/**
+ * AnySpend Platform API Client
+ *
+ * A headless TypeScript client for the AnySpend Platform REST API.
+ * Works in any runtime with `fetch` (Node.js, browsers, Cloudflare Workers, Deno, Bun).
+ *
+ * @example
+ * ```typescript
+ * import { AnySpendPlatformClient } from '@b3dotfun/sdk/anyspend/platform';
+ *
+ * const platform = new AnySpendPlatformClient('asp_your_api_key_here');
+ *
+ * // Create a payment link
+ * const link = await platform.paymentLinks.create({
+ *   name: 'Summer Sale',
+ *   amount: '10000000',
+ *   token_address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+ *   chain_id: 8453,
+ *   recipient_address: '0x...',
+ * });
+ *
+ * // Quick pay (no API key needed)
+ * const quickLink = await AnySpendPlatformClient.quickPay({
+ *   recipient_address: '0x...',
+ *   amount: '5000000',
+ * });
+ * ```
+ */
+
+import { HttpClient, StaticHttpClient, DEFAULT_BASE_URL, type ClientConfig } from "./client";
+import { PaymentLinksResource } from "./resources/payment-links";
+import { ProductsResource } from "./resources/products";
+import { CustomersResource } from "./resources/customers";
+import { TransactionsResource } from "./resources/transactions";
+import { CheckoutSessionsResource } from "./resources/checkout-sessions";
+import { WebhooksResource } from "./resources/webhooks";
+import { DiscountCodesResource } from "./resources/discount-codes";
+import { NotificationsResource } from "./resources/notifications";
+import { WidgetsResource } from "./resources/widgets";
+import { OrganizationResource } from "./resources/organization";
+import { AnalyticsResource } from "./resources/analytics";
+import { EventsResource } from "./resources/events";
+import type { QuickPayParams, PaymentLink } from "./types";
+
+export class AnySpendPlatformClient {
+  private client: HttpClient;
+
+  /** Payment Links - Create, manage, and track payment links */
+  readonly paymentLinks: PaymentLinksResource;
+
+  /** Products - Manage your product catalog */
+  readonly products: ProductsResource;
+
+  /** Customers - Manage customer records */
+  readonly customers: CustomersResource;
+
+  /** Transactions - View transaction history and stats */
+  readonly transactions: TransactionsResource;
+
+  /** Checkout Sessions - Server-side checkout management */
+  readonly checkoutSessions: CheckoutSessionsResource;
+
+  /** Webhooks - Configure webhook endpoints */
+  readonly webhooks: WebhooksResource;
+
+  /** Discount Codes - Create and validate discounts */
+  readonly discountCodes: DiscountCodesResource;
+
+  /** Notifications - Email and Telegram settings */
+  readonly notifications: NotificationsResource;
+
+  /** Widgets - Embeddable widget configurations */
+  readonly widgets: WidgetsResource;
+
+  /** Organization - Org settings and defaults */
+  readonly organization: OrganizationResource;
+
+  /** Analytics - Revenue and conversion analytics */
+  readonly analytics: AnalyticsResource;
+
+  /** Events - API audit trail */
+  readonly events: EventsResource;
+
+  /**
+   * Create a new AnySpend Platform API client.
+   *
+   * @param apiKey - Your API key (starts with `asp_`)
+   * @param config - Optional configuration
+   */
+  constructor(apiKey: string, config?: ClientConfig) {
+    this.client = new HttpClient(apiKey, config);
+
+    this.paymentLinks = new PaymentLinksResource(this.client);
+    this.products = new ProductsResource(this.client);
+    this.customers = new CustomersResource(this.client);
+    this.transactions = new TransactionsResource(this.client);
+    this.checkoutSessions = new CheckoutSessionsResource(this.client);
+    this.webhooks = new WebhooksResource(this.client);
+    this.discountCodes = new DiscountCodesResource(this.client);
+    this.notifications = new NotificationsResource(this.client);
+    this.widgets = new WidgetsResource(this.client);
+    this.organization = new OrganizationResource(this.client);
+    this.analytics = new AnalyticsResource(this.client);
+    this.events = new EventsResource(this.client);
+  }
+
+  /**
+   * Create a quick payment link without authentication.
+   * Rate limited to 5 requests per minute per IP.
+   *
+   * @param params - Quick pay parameters
+   * @param baseUrl - Optional API base URL (defaults to production)
+   */
+  static async quickPay(params: QuickPayParams, baseUrl: string = DEFAULT_BASE_URL): Promise<PaymentLink> {
+    return StaticHttpClient.post<PaymentLink>(baseUrl, "/quick-pay", params as unknown as Record<string, unknown>);
+  }
+}
+
+// Re-export types and errors
+export type { ClientConfig } from "./client";
+export {
+  ApiError,
+  AuthenticationError,
+  PermissionError,
+  RateLimitError,
+  NotFoundError,
+  IdempotencyError,
+} from "./errors";
+export type * from "./types";

package/src/anyspend/platform/resources/analytics.ts

@@ -0,0 +1,10 @@
+import type { HttpClient } from "../client";
+import type { AnalyticsOverview } from "../types";
+
+export class AnalyticsResource {
+  constructor(private client: HttpClient) {}
+
+  async overview(period?: "7d" | "30d" | "90d" | "all"): Promise<AnalyticsOverview> {
+    return this.client.get<AnalyticsOverview>("/analytics/overview", period !== undefined ? { period } : undefined);
+  }
+}

package/src/anyspend/platform/resources/checkout-sessions.ts

@@ -0,0 +1,36 @@
+import type { HttpClient } from "../client";
+import { autoPaginate } from "../utils/pagination";
+import type { CheckoutSession, ListResponse, CreateCheckoutSessionParams, PaginationParams } from "../types";
+
+export interface ListCheckoutSessionsParams extends PaginationParams {
+  status?: "open" | "processing" | "completed" | "expired" | "failed";
+  payment_link_id?: string;
+  from?: number;
+  to?: number;
+}
+
+export class CheckoutSessionsResource {
+  constructor(private client: HttpClient) {}
+
+  async list(params?: ListCheckoutSessionsParams): Promise<ListResponse<CheckoutSession>> {
+    return this.client.get<ListResponse<CheckoutSession>>("/checkout-sessions", params);
+  }
+
+  async *listAutoPaginate(params?: Omit<ListCheckoutSessionsParams, "page">): AsyncGenerator<CheckoutSession> {
+    yield* autoPaginate<CheckoutSession>((page, limit) => this.list({ ...params, page, limit }), {
+      limit: params?.limit,
+    });
+  }
+
+  async create(params: CreateCheckoutSessionParams): Promise<CheckoutSession> {
+    return this.client.post<CheckoutSession>("/checkout-sessions", params);
+  }
+
+  async get(id: string): Promise<CheckoutSession> {
+    return this.client.get<CheckoutSession>(`/checkout-sessions/${id}`);
+  }
+
+  async expire(id: string): Promise<CheckoutSession> {
+    return this.client.post<CheckoutSession>(`/checkout-sessions/${id}/expire`);
+  }
+}

package/src/anyspend/platform/resources/customers.ts

@@ -0,0 +1,54 @@
+import type { HttpClient } from "../client";
+import { autoPaginate } from "../utils/pagination";
+import type {
+  Customer,
+  Transaction,
+  ListResponse,
+  DeletedResponse,
+  CreateCustomerParams,
+  UpdateCustomerParams,
+  ExportCustomersParams,
+  PaginationParams,
+} from "../types";
+
+export interface ListCustomersParams extends PaginationParams {
+  search?: string;
+  sort?: "created_at" | "updated_at" | "total_paid" | "transaction_count";
+  order?: "asc" | "desc";
+}
+
+export class CustomersResource {
+  constructor(private client: HttpClient) {}
+
+  async list(params?: ListCustomersParams): Promise<ListResponse<Customer>> {
+    return this.client.get<ListResponse<Customer>>("/customers", params);
+  }
+
+  async *listAutoPaginate(params?: Omit<ListCustomersParams, "page">): AsyncGenerator<Customer> {
+    yield* autoPaginate<Customer>((page, limit) => this.list({ ...params, page, limit }), { limit: params?.limit });
+  }
+
+  async create(params: CreateCustomerParams): Promise<Customer> {
+    return this.client.post<Customer>("/customers", params);
+  }
+
+  async get(id: string): Promise<Customer> {
+    return this.client.get<Customer>(`/customers/${id}`);
+  }
+
+  async update(id: string, params: UpdateCustomerParams): Promise<Customer> {
+    return this.client.patch<Customer>(`/customers/${id}`, params);
+  }
+
+  async delete(id: string): Promise<DeletedResponse> {
+    return this.client.delete<DeletedResponse>(`/customers/${id}`);
+  }
+
+  async transactions(id: string, params?: PaginationParams): Promise<ListResponse<Transaction>> {
+    return this.client.get<ListResponse<Transaction>>(`/customers/${id}/transactions`, params);
+  }
+
+  async export(params?: ExportCustomersParams): Promise<string> {
+    return this.client.get<string>("/customers/export", params);
+  }
+}

package/src/anyspend/platform/resources/discount-codes.ts

@@ -0,0 +1,63 @@
+import type { HttpClient } from "../client";
+import { autoPaginate } from "../utils/pagination";
+import type {
+  DiscountCode,
+  ListResponse,
+  DeletedResponse,
+  CreateDiscountCodeParams,
+  BatchCreateDiscountCodesParams,
+  ValidateDiscountResult,
+  BatchCreateResult,
+  PaginationParams,
+} from "../types";
+
+export interface ListDiscountCodesParams extends PaginationParams {
+  payment_link_id?: string;
+  active?: "true" | "false";
+  search?: string;
+}
+
+export interface UpdateDiscountCodeParams {
+  is_active?: boolean;
+  max_uses?: number;
+  min_order_amount?: string;
+  expires_at?: number;
+}
+
+export interface ValidateDiscountParams {
+  code: string;
+  payment_link_id?: string;
+  amount?: string;
+}
+
+export class DiscountCodesResource {
+  constructor(private client: HttpClient) {}
+
+  async list(params?: ListDiscountCodesParams): Promise<ListResponse<DiscountCode>> {
+    return this.client.get<ListResponse<DiscountCode>>("/discount-codes", params);
+  }
+
+  async *listAutoPaginate(params?: Omit<ListDiscountCodesParams, "page">): AsyncGenerator<DiscountCode> {
+    yield* autoPaginate<DiscountCode>((page, limit) => this.list({ ...params, page, limit }), { limit: params?.limit });
+  }
+
+  async create(params: CreateDiscountCodeParams): Promise<DiscountCode> {
+    return this.client.post<DiscountCode>("/discount-codes", params);
+  }
+
+  async update(id: string, params: UpdateDiscountCodeParams): Promise<DiscountCode> {
+    return this.client.patch<DiscountCode>(`/discount-codes/${id}`, params);
+  }
+
+  async delete(id: string): Promise<DeletedResponse> {
+    return this.client.delete<DeletedResponse>(`/discount-codes/${id}`);
+  }
+
+  async validate(params: ValidateDiscountParams): Promise<ValidateDiscountResult> {
+    return this.client.post<ValidateDiscountResult>("/discount-codes/validate", params);
+  }
+
+  async batchCreate(params: BatchCreateDiscountCodesParams): Promise<BatchCreateResult> {
+    return this.client.post<BatchCreateResult>("/discount-codes/batch", params);
+  }
+}

package/src/anyspend/platform/resources/events.ts

@@ -0,0 +1,22 @@
+import type { HttpClient } from "../client";
+import { autoPaginate } from "../utils/pagination";
+import type { ApiEvent, ListResponse, PaginationParams } from "../types";
+
+export interface ListEventsParams extends PaginationParams {
+  event_type?: string;
+  resource_type?: string;
+  from?: number;
+  to?: number;
+}
+
+export class EventsResource {
+  constructor(private client: HttpClient) {}
+
+  async list(params?: ListEventsParams): Promise<ListResponse<ApiEvent>> {
+    return this.client.get<ListResponse<ApiEvent>>("/events", params);
+  }
+
+  async *listAutoPaginate(params?: Omit<ListEventsParams, "page">): AsyncGenerator<ApiEvent> {
+    yield* autoPaginate<ApiEvent>((page, limit) => this.list({ ...params, page, limit }), { limit: params?.limit });
+  }
+}

package/src/anyspend/platform/resources/notifications.ts

@@ -0,0 +1,37 @@
+import type { HttpClient } from "../client";
+import type { NotificationSettings, UpdateNotificationSettingsParams, ActionResponse } from "../types";
+
+export interface TelegramLinkResult {
+  object: "telegram_link";
+  link_url: string;
+  link_code: string;
+  expires_at: number;
+}
+
+export class NotificationsResource {
+  constructor(private client: HttpClient) {}
+
+  async get(): Promise<NotificationSettings> {
+    return this.client.get<NotificationSettings>("/notifications");
+  }
+
+  async update(params: UpdateNotificationSettingsParams): Promise<NotificationSettings> {
+    return this.client.patch<NotificationSettings>("/notifications", params);
+  }
+
+  async linkTelegram(): Promise<TelegramLinkResult> {
+    return this.client.post<TelegramLinkResult>("/notifications/telegram/link");
+  }
+
+  async unlinkTelegram(): Promise<ActionResponse> {
+    return this.client.post<ActionResponse>("/notifications/telegram/unlink");
+  }
+
+  async testEmail(): Promise<ActionResponse> {
+    return this.client.post<ActionResponse>("/notifications/test/email");
+  }
+
+  async testTelegram(): Promise<ActionResponse> {
+    return this.client.post<ActionResponse>("/notifications/test/telegram");
+  }
+}

package/src/anyspend/platform/resources/organization.ts

@@ -0,0 +1,24 @@
+import type { HttpClient } from "../client";
+import type { Organization } from "../types";
+
+export interface UpdateOrganizationParams {
+  name?: string;
+  description?: string;
+  logo_url?: string;
+  website_url?: string;
+  default_recipient_address?: string;
+  default_chain_id?: number;
+  default_token_address?: string;
+}
+
+export class OrganizationResource {
+  constructor(private client: HttpClient) {}
+
+  async get(): Promise<Organization> {
+    return this.client.get<Organization>("/organization");
+  }
+
+  async update(params: UpdateOrganizationParams): Promise<Organization> {
+    return this.client.patch<Organization>("/organization", params);
+  }
+}