convex-saligpay 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SaligPay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,288 @@
+# @convex/saligpay
+
+Convex component for SaligPay payment integration. This package provides a self-contained Convex component with its own database tables and functions for integrating SaligPay payment processing.
+
+## Features
+
+- 🔐 **OAuth Authentication** - Secure token-based authentication with automatic refresh
+- 💳 **Checkout Sessions** - Create and manage payment checkout sessions
+- 💰 **Payment Intents** - Handle payment intents with 3D Secure support
+- 🎣 **Webhook Handling** - Receive and verify webhook events from SaligPay
+- 🔒 **Type Safety** - Full TypeScript support with exported types
+- 📦 **Isolated Data** - Component has its own database tables, isolated from your app
+
+## Installation
+
+```bash
+npm install @convex/saligpay convex
+```
+
+## Quick Start
+
+### 1. Add the Component
+
+In your app's `convex/convex.config.ts`:
+
+```typescript
+import { defineApp } from "convex/server";
+import saligpay from "@convex/saligpay/convex.config.js";
+
+const app = defineApp();
+app.use(saligpay);
+// Or with a custom name:
+// app.use(saligpay, { name: "payments" });
+
+export default app;
+```
+
+### 2. Run Convex Dev
+
+```bash
+npx convex dev
+```
+
+This generates the component's API in `convex/_generated/api.js`.
+
+### 3. Use in Your Functions
+
+```typescript
+import { action, mutation } from "./_generated/server";
+import { components } from "./_generated/api.js";
+import { SaligPayComponent } from "@convex/saligpay";
+
+const saligpay = new SaligPayComponent(components.saligpay);
+
+export const createPayment = mutation({
+    args: {
+        merchantId: v.string(),
+        amount: v.number(),
+        description: v.string(),
+    },
+    handler: async (ctx, args) => {
+        // Authenticate first
+        await ctx.runMutation(saligpay.auth.authenticate, {
+            merchantId: args.merchantId,
+            clientId: "your-client-id",
+            clientSecret: "your-client-secret",
+            env: "sandbox",
+        });
+
+        // Create checkout
+        const checkout = await ctx.runMutation(saligpay.checkout.create, {
+            merchantId: args.merchantId,
+            externalId: `order-${Date.now()}`,
+            amount: args.amount,
+            description: args.description,
+            webhookUrl: "https://yourapp.com/api/webhooks/saligpay",
+            returnUrl: "https://yourapp.com/payment/success",
+        });
+
+        return checkout.checkoutUrl;
+    },
+});
+```
+
+### 4. Set Up Webhooks (Optional)
+
+In your app's `convex/http.ts`:
+
+```typescript
+import { httpRouter } from "convex/server";
+import { components } from "./_generated/api.js";
+
+const http = httpRouter();
+
+http.route({
+    path: "/api/webhooks/saligpay",
+    method: "POST",
+    handler: async (ctx, request) => {
+        const body = await request.text();
+        const signature = request.headers.get("x-saligpay-signature") || "";
+        const timestamp = request.headers.get("x-saligpay-timestamp") || "";
+        const secret = request.headers.get("x-saligpay-webhook-secret") || "";
+
+        const result = await ctx.runMutation(
+            components.saligpay.lib.webhookActions.receiveWebhook,
+            {
+                payload: body,
+                signature,
+                timestamp,
+                signingSecret: secret,
+            },
+        );
+
+        return new Response(JSON.stringify(result), {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+        });
+    },
+});
+
+export default http;
+```
+
+## API Reference
+
+### Using the Component API Directly
+
+```typescript
+import { components } from "./_generated/api.js";
+
+// Queries
+await ctx.runQuery(components.saligpay.lib.auth.getStoredTokens, { merchantId });
+await ctx.runQuery(components.saligpay.lib.checkout.getSession, { externalId });
+await ctx.runQuery(components.saligpay.lib.paymentIntent.getPaymentIntentStatus, { intentId });
+
+// Mutations
+await ctx.runMutation(components.saligpay.lib.authMutations.authenticate, { ... });
+await ctx.runMutation(components.saligpay.lib.checkoutActions.createCheckout, { ... });
+await ctx.runMutation(components.saligpay.lib.paymentIntentActions.createPaymentIntent, { ... });
+```
+
+### Using the Client Wrapper
+
+```typescript
+import { SaligPayComponent, makeSaligPayComponent } from "@convex/saligpay";
+import { components } from "./_generated/api.js";
+
+const saligpay = makeSaligPayComponent(components.saligpay);
+// or: const saligpay = new SaligPayComponent(components.saligpay);
+
+// Auth
+await ctx.runMutation(saligpay.auth.authenticate, { merchantId, clientId, clientSecret });
+await ctx.runQuery(saligpay.auth.getStoredTokens, { merchantId });
+
+// Checkout
+await ctx.runMutation(saligpay.checkout.create, { merchantId, amount, ... });
+await ctx.runQuery(saligpay.checkout.getSession, { externalId });
+
+// Payment Intent
+await ctx.runMutation(saligpay.paymentIntent.create, { merchantId, amount, ... });
+await ctx.runQuery(saligpay.paymentIntent.getStatus, { intentId });
+
+// Webhooks
+await ctx.runMutation(saligpay.webhook.receive, { payload, signature, timestamp, signingSecret });
+```
+
+### Authentication
+
+| Function                      | Type           | Description                               |
+| ----------------------------- | -------------- | ----------------------------------------- |
+| `authenticate`                | mutation       | Get OAuth tokens using client credentials |
+| `refreshToken`                | mutation       | Refresh expired access tokens             |
+| `getStoredTokens`             | query          | Retrieve stored tokens for a merchant     |
+| `getMerchantCredentials`      | internal query | Get stored credentials (internal use)     |
+| `validateToken`               | query          | Check if tokens are valid                 |
+| `loginAndRetrieveCredentials` | action         | Full OAuth flow with email/password       |
+| `internalAuthentication`      | action         | Authenticate by user ID                   |
+
+### Checkout
+
+| Function           | Type     | Description                             |
+| ------------------ | -------- | --------------------------------------- |
+| `createCheckout`   | mutation | Create a new checkout session           |
+| `getSession`       | query    | Get checkout by externalId or sessionId |
+| `getCheckoutByUrl` | query    | Get checkout by session token           |
+| `listCheckouts`    | query    | List checkouts for a merchant           |
+| `expireSession`    | mutation | Mark a session as expired               |
+
+### Payment Intents
+
+| Function                 | Type     | Description                 |
+| ------------------------ | -------- | --------------------------- |
+| `createPaymentIntent`    | mutation | Create a payment intent     |
+| `confirmPaymentIntent`   | mutation | Confirm with payment method |
+| `getPaymentIntentStatus` | query    | Get current status          |
+| `listPaymentIntents`     | query    | List intents for a merchant |
+| `cancelPaymentIntent`    | mutation | Cancel an intent            |
+
+### Webhooks
+
+| Function                       | Type     | Description                |
+| ------------------------------ | -------- | -------------------------- |
+| `receiveWebhook`               | mutation | Receive and verify webhook |
+| `handleCheckoutCompleted`      | mutation | Handle completed checkout  |
+| `handleCheckoutFailed`         | mutation | Handle failed checkout     |
+| `handlePaymentIntentSucceeded` | mutation | Handle successful payment  |
+| `handleRefundCreated`          | mutation | Handle refund creation     |
+
+## Component Tables
+
+The component creates these isolated tables:
+
+- `saligpayTokens` - OAuth tokens per merchant
+- `saligpayCredentials` - Merchant credentials (encrypted)
+- `checkoutSessions` - Checkout session records
+- `paymentIntents` - Payment intent records
+- `webhookEvents` - Webhook event audit log
+
+## Type Exports
+
+```typescript
+import type {
+    SaligPayConfig,
+    SaligPayAuthTokens,
+    CheckoutSession,
+    PaymentIntent,
+    SaligPayWebhookPayload,
+    StoredTokens,
+    MerchantCredentials,
+    CreateCheckoutOptions,
+    CreatePaymentIntentOptions,
+} from "@convex/saligpay";
+```
+
+## Development
+
+### Building the Component
+
+```bash
+npm run build
+```
+
+This builds the component to `dist/` with all entry points needed for publishing.
+
+### Development with Example App
+
+The `example/` folder contains a test app that uses the component. To develop:
+
+```bash
+# 1. Build the component
+npm run build
+
+# 2. From the example app, run convex dev (requires Convex deployment)
+cd example
+npx convex dev
+```
+
+Running `npx convex dev` in the example app will:
+
+1. Generate the component's `_generated` types
+2. Deploy the component to your Convex deployment
+3. Watch for changes
+
+### Workflow for Component Development
+
+1. Make changes to `src/convex/*.ts` files
+2. Run `npm run build` to rebuild
+3. In example app, `npx convex dev` picks up changes automatically
+
+**Note:** The component's `_generated` folder contains stub types that allow building without a Convex deployment. When used in an actual app, Convex generates the real types.
+
+## Testing
+
+When writing tests with `convex-test`, register the component:
+
+```typescript
+import { convexTest } from "convex-test";
+import saligpayTest from "@convex/saligpay/test";
+import schema from "./convex/schema.js";
+const modules = import.meta.glob("./convex/**/*.ts");
+
+const t = convexTest(schema, modules);
+saligpayTest.register(t, "saligpay");
+```
+
+## License
+
+MIT © SaligPay

package/dist/client/index.d.ts

@@ -0,0 +1,169 @@
+import type { Auth, GenericActionCtx, GenericDataModel } from "convex/server";
+import type { ComponentApi } from "../component/_generated/component.js";
+export declare function createCheckout(ctx: {
+    runMutation: GenericActionCtx<GenericDataModel>["runMutation"];
+}, component: ComponentApi, args: {
+    merchantId: string;
+    externalId: string;
+    amount: number;
+    description: string;
+    webhookUrl?: string;
+    returnUrl?: string;
+    metadata?: Record<string, unknown>;
+}): Promise<any>;
+export declare function getSession(ctx: {
+    runQuery: GenericActionCtx<GenericDataModel>["runQuery"];
+}, component: ComponentApi, args: {
+    externalId?: string;
+    sessionId?: string;
+}): Promise<any>;
+export declare function listCheckouts(ctx: {
+    runQuery: GenericActionCtx<GenericDataModel>["runQuery"];
+}, component: ComponentApi, args: {
+    merchantId: string;
+    status?: string;
+    limit?: number;
+}): Promise<any>;
+export declare function createPaymentIntent(ctx: {
+    runMutation: GenericActionCtx<GenericDataModel>["runMutation"];
+}, component: ComponentApi, args: {
+    merchantId: string;
+    amount: number;
+    description?: string;
+    externalId?: string;
+    webhookUrl?: string;
+    returnUrl?: string;
+    metadata?: Record<string, unknown>;
+}): Promise<any>;
+export declare function confirmPaymentIntent(ctx: {
+    runMutation: GenericActionCtx<GenericDataModel>["runMutation"];
+}, component: ComponentApi, args: {
+    merchantId: string;
+    intentId: string;
+    paymentMethod: string;
+}): Promise<any>;
+export declare function getPaymentIntentStatus(ctx: {
+    runQuery: GenericActionCtx<GenericDataModel>["runQuery"];
+}, component: ComponentApi, args: {
+    intentId: string;
+}): Promise<any>;
+export declare function listPaymentIntents(ctx: {
+    runQuery: GenericActionCtx<GenericDataModel>["runQuery"];
+}, component: ComponentApi, args: {
+    merchantId: string;
+    status?: string;
+    limit?: number;
+}): Promise<any>;
+export declare function receiveWebhook(ctx: {
+    runMutation: GenericActionCtx<GenericDataModel>["runMutation"];
+}, component: ComponentApi, args: {
+    payload: string;
+    signature: string;
+    timestamp: string;
+    signingSecret: string;
+}): Promise<any>;
+export declare function exposeApi(component: ComponentApi, options: {
+    auth: (ctx: {
+        auth: Auth;
+    }, operation: {
+        type: "read";
+        merchantId: string;
+    } | {
+        type: "write";
+        merchantId: string;
+    }) => Promise<string>;
+}): {
+    authenticate: import("convex/server").RegisteredMutation<"public", {
+        clientId?: string | undefined;
+        clientSecret?: string | undefined;
+        env?: "sandbox" | "production" | undefined;
+        merchantId: string;
+    }, Promise<any>>;
+    getStoredTokens: import("convex/server").RegisteredQuery<"public", {
+        merchantId: string;
+    }, Promise<any>>;
+    validateToken: import("convex/server").RegisteredQuery<"public", {
+        merchantId: string;
+    }, Promise<any>>;
+    createCheckout: import("convex/server").RegisteredMutation<"public", {
+        webhookUrl?: string | undefined;
+        returnUrl?: string | undefined;
+        metadata?: Record<string, any> | undefined;
+        merchantId: string;
+        externalId: string;
+        amount: number;
+        description: string;
+    }, Promise<any>>;
+    getSession: import("convex/server").RegisteredQuery<"public", {
+        externalId?: string | undefined;
+        sessionId?: string | undefined;
+    }, Promise<any>>;
+    listCheckouts: import("convex/server").RegisteredQuery<"public", {
+        status?: string | undefined;
+        limit?: number | undefined;
+        merchantId: string;
+    }, Promise<any>>;
+    createPaymentIntent: import("convex/server").RegisteredMutation<"public", {
+        externalId?: string | undefined;
+        description?: string | undefined;
+        webhookUrl?: string | undefined;
+        returnUrl?: string | undefined;
+        metadata?: Record<string, any> | undefined;
+        merchantId: string;
+        amount: number;
+    }, Promise<any>>;
+    confirmPaymentIntent: import("convex/server").RegisteredMutation<"public", {
+        merchantId: string;
+        intentId: string;
+        paymentMethod: string;
+    }, Promise<any>>;
+    getPaymentIntentStatus: import("convex/server").RegisteredQuery<"public", {
+        intentId: string;
+    }, Promise<any>>;
+    listPaymentIntents: import("convex/server").RegisteredQuery<"public", {
+        status?: string | undefined;
+        limit?: number | undefined;
+        merchantId: string;
+    }, Promise<any>>;
+    receiveWebhook: import("convex/server").RegisteredMutation<"public", {
+        payload: string;
+        signature: string;
+        timestamp: string;
+        signingSecret: string;
+    }, Promise<any>>;
+};
+export declare class SaligPayComponent {
+    component: ComponentApi;
+    constructor(component: ComponentApi);
+    get auth(): {
+        authenticate: import("convex/server").FunctionReference<"mutation", "public">;
+        refreshToken: import("convex/server").FunctionReference<"mutation", "public">;
+        getStoredTokens: import("convex/server").FunctionReference<"query", "public">;
+        validateToken: import("convex/server").FunctionReference<"query", "public">;
+        loginAndRetrieveCredentials: import("convex/server").FunctionReference<"action", "public">;
+        internalAuthentication: import("convex/server").FunctionReference<"action", "public">;
+    };
+    get checkout(): {
+        create: import("convex/server").FunctionReference<"mutation", "public">;
+        getSession: import("convex/server").FunctionReference<"query", "public">;
+        getCheckoutByUrl: import("convex/server").FunctionReference<"query", "public">;
+        listCheckouts: import("convex/server").FunctionReference<"query", "public">;
+        expireSession: import("convex/server").FunctionReference<"mutation", "public">;
+    };
+    get paymentIntent(): {
+        create: import("convex/server").FunctionReference<"mutation", "public">;
+        confirm: import("convex/server").FunctionReference<"mutation", "public">;
+        getStatus: import("convex/server").FunctionReference<"query", "public">;
+        list: import("convex/server").FunctionReference<"query", "public">;
+        cancel: import("convex/server").FunctionReference<"mutation", "public">;
+    };
+    get webhook(): {
+        receive: import("convex/server").FunctionReference<"mutation", "public">;
+        handleCheckoutCompleted: import("convex/server").FunctionReference<"mutation", "public">;
+        handleCheckoutFailed: import("convex/server").FunctionReference<"mutation", "public">;
+        handlePaymentIntentSucceeded: import("convex/server").FunctionReference<"mutation", "public">;
+        handleRefundCreated: import("convex/server").FunctionReference<"mutation", "public">;
+    };
+}
+export declare function makeSaligPayComponent(component: ComponentApi): SaligPayComponent;
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

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