@surgent-dev/surpay-convex 0.1.0

package/README.md

@@ -0,0 +1,84 @@
+# @surgent-dev/surpay-convex
+
+Convex integration for Surpay SDK.
+
+## Install
+
+```bash
+npm install @surgent-dev/surpay-convex
+```
+
+## Setup
+
+Step 1: Create `convex/surpay.ts`
+
+```typescript
+import { Surpay } from "@surgent-dev/surpay-convex";
+
+const surpay = new Surpay({
+  apiKey: process.env.SURPAY_API_KEY!,
+});
+
+export const {
+  createCheckout,
+  getCustomer,
+  listCustomers,
+  listSubscriptions,
+} = surpay.api();
+```
+
+Step 2: Set environment variable
+
+Add `SURPAY_API_KEY` to your Convex dashboard environment variables.
+
+## Usage
+
+### Create Checkout
+
+```typescript
+import { api } from "./_generated/api";
+
+// Inside a Convex action or from client
+const { data, error } = await ctx.runAction(api.surpay.createCheckout, {
+  product_id: "prod_123",
+  price_id: "price_123",
+  success_url: "https://example.com/success",
+  cancel_url: "https://example.com/cancel",
+});
+
+if (error) {
+  console.error(error.message);
+} else {
+  console.log(data.checkout_url);
+}
+```
+
+### Get Customer
+
+```typescript
+import { api } from "./_generated/api";
+
+const { data, error } = await ctx.runAction(api.surpay.getCustomer, {
+  project_id: "proj_123",
+  customer_id: "cust_123",
+});
+```
+
+### List Subscriptions
+
+```typescript
+import { api } from "./_generated/api";
+
+const { data, error } = await ctx.runAction(api.surpay.listSubscriptions, {
+  project_id: "proj_123",
+});
+```
+
+## API Reference
+
+| Action | Args | Returns |
+|--------|------|---------|
+| `createCheckout` | `product_id`, `price_id`, `success_url`, `cancel_url` | `{ checkout_url: string, session_id: string }` |
+| `getCustomer` | `project_id`, `customer_id` | `CustomerWithDetails` |
+| `listCustomers` | `project_id` | `Customer[]` |
+| `listSubscriptions` | `project_id` | `Subscription[]` |

package/dist/index.d.ts

@@ -0,0 +1,74 @@
+import { Surpay as SurpayClient } from "@surgent-dev/surpay";
+export type IdentifierOpts = {
+    customerId: string;
+    customerData?: {
+        name?: string;
+        email?: string;
+    };
+};
+export type SurpayConfig = {
+    apiKey: string;
+    baseUrl?: string;
+    identify: (ctx: any) => Promise<IdentifierOpts | null>;
+};
+type PlainError = {
+    message: string;
+    code?: string;
+};
+export declare class Surpay {
+    private client;
+    private options;
+    constructor(config: SurpayConfig);
+    getIdentifierOpts(ctx: any): Promise<IdentifierOpts | null>;
+    getAuthParams({ ctx, requireAuth, }: {
+        ctx: any;
+        requireAuth?: boolean;
+    }): Promise<{
+        client: SurpayClient;
+        identifierOpts: IdentifierOpts | null;
+    }>;
+    api(): {
+        createCheckout: import("convex/server").RegisteredAction<"public", {
+            product_id: string;
+            price_id: string;
+            success_url: string;
+            cancel_url: string;
+        }, Promise<{
+            data: null;
+            error: PlainError;
+        } | {
+            data: import("@surgent-dev/surpay").CreateCheckoutResponse;
+            error: null;
+        }>>;
+        getCustomer: import("convex/server").RegisteredAction<"public", {
+            project_id: string;
+            customer_id: string;
+        }, Promise<{
+            data: null;
+            error: PlainError;
+        } | {
+            data: import("@surgent-dev/surpay").CustomerWithDetails;
+            error: null;
+        }>>;
+        listCustomers: import("convex/server").RegisteredAction<"public", {
+            project_id: string;
+        }, Promise<{
+            data: null;
+            error: PlainError;
+        } | {
+            data: import("@surgent-dev/surpay").Customer[];
+            error: null;
+        }>>;
+        listSubscriptions: import("convex/server").RegisteredAction<"public", {
+            project_id: string;
+        }, Promise<{
+            data: null;
+            error: PlainError;
+        } | {
+            data: import("@surgent-dev/surpay").Subscription[];
+            error: null;
+        }>>;
+    };
+}
+export * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAyBA,OAAO,EAAE,MAAM,IAAI,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAQ7D,MAAM,MAAM,cAAc,GAAG;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;CACxD,CAAC;AAGF,KAAK,UAAU,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAwBrD,qBAAa,MAAM;IACjB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,OAAO,CAAe;gBAElB,MAAM,EAAE,YAAY;IAQ1B,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAI3D,aAAa,CAAC,EAClB,GAAG,EACH,WAAkB,GACnB,EAAE;QACD,GAAG,EAAE,GAAG,CAAC;QACT,WAAW,CAAC,EAAE,OAAO,CAAC;KACvB,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,YAAY,CAAC;QAAC,cAAc,EAAE,cAAc,GAAG,IAAI,CAAA;KAAE,CAAC;IAQ5E,GAAG;;;;;;;kBA1CyC,IAAI;mBAAS,UAAU;;;mBAAxC,IAAI;;;;;;kBAAa,IAAI;mBAAS,UAAU;;;mBAAxC,IAAI;;;;;kBAAa,IAAI;mBAAS,UAAU;;;mBAAxC,IAAI;;;;;kBAAa,IAAI;mBAAS,UAAU;;;mBAAxC,IAAI;;;CAyFhC;AAED,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,109 @@
+/**
+ * Surpay Convex Integration
+ *
+ * Provides Convex actions that wrap the Surpay SDK with auth context support.
+ *
+ * @example
+ * ```typescript
+ * // convex/surpay.ts
+ * import { Surpay } from "@surgent-dev/surpay-convex";
+ *
+ * const surpay = new Surpay({
+ *   apiKey: process.env.SURPAY_API_KEY!,
+ *   identify: async (ctx) => {
+ *     const identity = await ctx.auth.getUserIdentity();
+ *     if (!identity) return null;
+ *     return {
+ *       customerId: identity.subject,
+ *       customerData: { name: identity.name, email: identity.email },
+ *     };
+ *   },
+ * });
+ * export const { createCheckout, getCustomer, listCustomers, listSubscriptions } = surpay.api();
+ * ```
+ */
+import { actionGeneric } from "convex/server";
+import { Surpay as SurpayClient } from "@surgent-dev/surpay";
+import { CreateCheckoutArgs, GetCustomerArgs, ListCustomersArgs, ListSubscriptionsArgs, } from "./types.js";
+function toPlainError(error) {
+    if (error instanceof Error) {
+        return { message: error.message, code: error.code };
+    }
+    return { message: String(error) };
+}
+// Wrap SDK calls to ensure errors are plain objects
+async function wrapSdkCall(fn) {
+    try {
+        const result = await fn();
+        if (result.error) {
+            return { data: null, error: toPlainError(result.error) };
+        }
+        return result;
+    }
+    catch (e) {
+        return { data: null, error: toPlainError(e) };
+    }
+}
+export class Surpay {
+    client;
+    options;
+    constructor(config) {
+        this.options = config;
+        this.client = new SurpayClient({
+            apiKey: config.apiKey,
+            baseUrl: config.baseUrl,
+        });
+    }
+    async getIdentifierOpts(ctx) {
+        return await this.options.identify(ctx);
+    }
+    async getAuthParams({ ctx, requireAuth = true, }) {
+        const identifierOpts = await this.getIdentifierOpts(ctx);
+        if (requireAuth && !identifierOpts) {
+            throw new Error("No customer identifier found");
+        }
+        return { client: this.client, identifierOpts };
+    }
+    api() {
+        return {
+            createCheckout: actionGeneric({
+                args: CreateCheckoutArgs,
+                handler: async (ctx, args) => {
+                    const { client, identifierOpts } = await this.getAuthParams({ ctx });
+                    // Merge customer info from auth context with checkout args
+                    const checkoutParams = {
+                        ...args,
+                        customer_id: identifierOpts.customerId,
+                        customer_name: identifierOpts.customerData?.name,
+                        customer_email: identifierOpts.customerData?.email,
+                    };
+                    return wrapSdkCall(() => client.checkout.create(checkoutParams));
+                },
+            }),
+            getCustomer: actionGeneric({
+                args: GetCustomerArgs,
+                handler: async (ctx, args) => {
+                    const { client, identifierOpts } = await this.getAuthParams({ ctx });
+                    const customerId = args.customer_id || identifierOpts.customerId;
+                    return wrapSdkCall(() => client.customers.get(args.project_id, customerId));
+                },
+            }),
+            listCustomers: actionGeneric({
+                args: ListCustomersArgs,
+                handler: async (ctx, args) => {
+                    const { client } = await this.getAuthParams({ ctx });
+                    return wrapSdkCall(() => client.customers.list(args.project_id));
+                },
+            }),
+            listSubscriptions: actionGeneric({
+                args: ListSubscriptionsArgs,
+                handler: async (ctx, args) => {
+                    const { client } = await this.getAuthParams({ ctx });
+                    return wrapSdkCall(() => client.subscriptions.list(args.project_id));
+                },
+            }),
+        };
+    }
+}
+export * from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Convex validators for Surpay action arguments
+ */
+import { Infer } from "convex/values";
+export declare const CreateCheckoutArgs: import("convex/values").VObject<{
+    product_id: string;
+    price_id: string;
+    success_url: string;
+    cancel_url: string;
+}, {
+    product_id: import("convex/values").VString<string, "required">;
+    price_id: import("convex/values").VString<string, "required">;
+    success_url: import("convex/values").VString<string, "required">;
+    cancel_url: import("convex/values").VString<string, "required">;
+}, "required", "product_id" | "price_id" | "success_url" | "cancel_url">;
+export type CreateCheckoutArgs = Infer<typeof CreateCheckoutArgs>;
+export declare const ListSubscriptionsArgs: import("convex/values").VObject<{
+    project_id: string;
+}, {
+    project_id: import("convex/values").VString<string, "required">;
+}, "required", "project_id">;
+export type ListSubscriptionsArgs = Infer<typeof ListSubscriptionsArgs>;
+export declare const GetCustomerArgs: import("convex/values").VObject<{
+    project_id: string;
+    customer_id: string;
+}, {
+    project_id: import("convex/values").VString<string, "required">;
+    customer_id: import("convex/values").VString<string, "required">;
+}, "required", "project_id" | "customer_id">;
+export type GetCustomerArgs = Infer<typeof GetCustomerArgs>;
+export declare const ListCustomersArgs: import("convex/values").VObject<{
+    project_id: string;
+}, {
+    project_id: import("convex/values").VString<string, "required">;
+}, "required", "project_id">;
+export type ListCustomersArgs = Infer<typeof ListCustomersArgs>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAK,KAAK,EAAE,MAAM,eAAe,CAAC;AAGzC,eAAO,MAAM,kBAAkB;;;;;;;;;;wEAK7B,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAGlE,eAAO,MAAM,qBAAqB;;;;4BAEhC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAGxE,eAAO,MAAM,eAAe;;;;;;4CAG1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAG5D,eAAO,MAAM,iBAAiB;;;;4BAE5B,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/types.js

@@ -0,0 +1,25 @@
+/**
+ * Convex validators for Surpay action arguments
+ */
+import { v } from "convex/values";
+// CreateCheckoutRequest: product_id, price_id, success_url, cancel_url (all required)
+export const CreateCheckoutArgs = v.object({
+    product_id: v.string(),
+    price_id: v.string(),
+    success_url: v.string(),
+    cancel_url: v.string(),
+});
+// ListSubscriptions: requires project_id
+export const ListSubscriptionsArgs = v.object({
+    project_id: v.string(),
+});
+// GetCustomer: requires project_id and customer_id
+export const GetCustomerArgs = v.object({
+    project_id: v.string(),
+    customer_id: v.string(),
+});
+// ListCustomers: requires project_id
+export const ListCustomersArgs = v.object({
+    project_id: v.string(),
+});
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,CAAC,EAAS,MAAM,eAAe,CAAC;AAEzC,sFAAsF;AACtF,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;CACvB,CAAC,CAAC;AAGH,yCAAyC;AACzC,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;CACvB,CAAC,CAAC;AAGH,mDAAmD;AACnD,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;CACxB,CAAC,CAAC;AAGH,qCAAqC;AACrC,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;CACvB,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@surgent-dev/surpay-convex",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@surgent-dev/surpay": "workspace:*"
+  },
+  "peerDependencies": {
+    "convex": "^1.25.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "convex": "^1.25.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,149 @@
+/**
+ * Surpay Convex Integration
+ *
+ * Provides Convex actions that wrap the Surpay SDK with auth context support.
+ *
+ * @example
+ * ```typescript
+ * // convex/surpay.ts
+ * import { Surpay } from "@surgent-dev/surpay-convex";
+ *
+ * const surpay = new Surpay({
+ *   apiKey: process.env.SURPAY_API_KEY!,
+ *   identify: async (ctx) => {
+ *     const identity = await ctx.auth.getUserIdentity();
+ *     if (!identity) return null;
+ *     return {
+ *       customerId: identity.subject,
+ *       customerData: { name: identity.name, email: identity.email },
+ *     };
+ *   },
+ * });
+ * export const { createCheckout, getCustomer, listCustomers, listSubscriptions } = surpay.api();
+ * ```
+ */
+import { actionGeneric } from "convex/server";
+import { Surpay as SurpayClient } from "@surgent-dev/surpay";
+import {
+  CreateCheckoutArgs,
+  GetCustomerArgs,
+  ListCustomersArgs,
+  ListSubscriptionsArgs,
+} from "./types.js";
+
+export type IdentifierOpts = {
+  customerId: string;
+  customerData?: { name?: string; email?: string };
+};
+
+export type SurpayConfig = {
+  apiKey: string;
+  baseUrl?: string;
+  identify: (ctx: any) => Promise<IdentifierOpts | null>;
+};
+
+// Convex can't serialize class instances - convert errors to plain objects
+type PlainError = { message: string; code?: string };
+
+function toPlainError(error: unknown): PlainError {
+  if (error instanceof Error) {
+    return { message: error.message, code: (error as { code?: string }).code };
+  }
+  return { message: String(error) };
+}
+
+// Wrap SDK calls to ensure errors are plain objects
+async function wrapSdkCall<T>(
+  fn: () => Promise<{ data: T; error: null } | { data: null; error: unknown }>
+): Promise<{ data: T; error: null } | { data: null; error: PlainError }> {
+  try {
+    const result = await fn();
+    if (result.error) {
+      return { data: null, error: toPlainError(result.error) };
+    }
+    return result as { data: T; error: null };
+  } catch (e) {
+    return { data: null, error: toPlainError(e) };
+  }
+}
+
+export class Surpay {
+  private client: SurpayClient;
+  private options: SurpayConfig;
+
+  constructor(config: SurpayConfig) {
+    this.options = config;
+    this.client = new SurpayClient({
+      apiKey: config.apiKey,
+      baseUrl: config.baseUrl,
+    });
+  }
+
+  async getIdentifierOpts(ctx: any): Promise<IdentifierOpts | null> {
+    return await this.options.identify(ctx);
+  }
+
+  async getAuthParams({
+    ctx,
+    requireAuth = true,
+  }: {
+    ctx: any;
+    requireAuth?: boolean;
+  }): Promise<{ client: SurpayClient; identifierOpts: IdentifierOpts | null }> {
+    const identifierOpts = await this.getIdentifierOpts(ctx);
+    if (requireAuth && !identifierOpts) {
+      throw new Error("No customer identifier found");
+    }
+    return { client: this.client, identifierOpts };
+  }
+
+  api() {
+    return {
+      createCheckout: actionGeneric({
+        args: CreateCheckoutArgs,
+        handler: async (ctx, args) => {
+          const { client, identifierOpts } = await this.getAuthParams({ ctx });
+          // Merge customer info from auth context with checkout args
+          const checkoutParams = {
+            ...args,
+            customer_id: identifierOpts!.customerId,
+            customer_name: identifierOpts!.customerData?.name,
+            customer_email: identifierOpts!.customerData?.email,
+          };
+          return wrapSdkCall(() =>
+            client.checkout.create(checkoutParams as Parameters<typeof client.checkout.create>[0])
+          );
+        },
+      }),
+
+      getCustomer: actionGeneric({
+        args: GetCustomerArgs,
+        handler: async (ctx, args) => {
+          const { client, identifierOpts } = await this.getAuthParams({ ctx });
+          const customerId = args.customer_id || identifierOpts!.customerId;
+          return wrapSdkCall(() =>
+            client.customers.get(args.project_id, customerId)
+          );
+        },
+      }),
+
+      listCustomers: actionGeneric({
+        args: ListCustomersArgs,
+        handler: async (ctx, args) => {
+          const { client } = await this.getAuthParams({ ctx });
+          return wrapSdkCall(() => client.customers.list(args.project_id));
+        },
+      }),
+
+      listSubscriptions: actionGeneric({
+        args: ListSubscriptionsArgs,
+        handler: async (ctx, args) => {
+          const { client } = await this.getAuthParams({ ctx });
+          return wrapSdkCall(() => client.subscriptions.list(args.project_id));
+        },
+      }),
+    };
+  }
+}
+
+export * from "./types.js";

package/src/types.ts

@@ -0,0 +1,32 @@
+/**
+ * Convex validators for Surpay action arguments
+ */
+import { v, Infer } from "convex/values";
+
+// CreateCheckoutRequest: product_id, price_id, success_url, cancel_url (all required)
+export const CreateCheckoutArgs = v.object({
+  product_id: v.string(),
+  price_id: v.string(),
+  success_url: v.string(),
+  cancel_url: v.string(),
+});
+export type CreateCheckoutArgs = Infer<typeof CreateCheckoutArgs>;
+
+// ListSubscriptions: requires project_id
+export const ListSubscriptionsArgs = v.object({
+  project_id: v.string(),
+});
+export type ListSubscriptionsArgs = Infer<typeof ListSubscriptionsArgs>;
+
+// GetCustomer: requires project_id and customer_id
+export const GetCustomerArgs = v.object({
+  project_id: v.string(),
+  customer_id: v.string(),
+});
+export type GetCustomerArgs = Infer<typeof GetCustomerArgs>;
+
+// ListCustomers: requires project_id
+export const ListCustomersArgs = v.object({
+  project_id: v.string(),
+});
+export type ListCustomersArgs = Infer<typeof ListCustomersArgs>;

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}