@payclave/sdk-server 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# @payclave/sdk-server
+
+## 0.1.0
+
+Initial production-ready release.
+
+### Added
+
+- `createPayclaveServerClient` for secret-key server integrations.
+- Typed checkout session, invoice, payment, webhook endpoint, test webhook, and webhook delivery helpers.
+- `Idempotency-Key` support for checkout-session and invoice creation.
+- Abort and timeout support on every API request.
+- Structured `PayclaveError` with `code`, `status`, `requestId`, `details`, and `cause`.
+- Exported typed API, SDK, and webhook verification error-code vocabularies.
+- Client-side guards for invalid base URLs, timeouts, identifiers, expiry windows, metadata, webhook URLs, event types, and non-serializable request bodies.
+- Node-side Payclave webhook signature verification and event construction helpers.
+- Dual ESM/CJS build with TypeScript declarations.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Payclave
+
+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,162 @@
+# @payclave/sdk-server
+
+TypeScript server SDK for [Payclave](https://payclave.com) — non-custodial crypto checkout for merchants.
+
+Use this package from your backend with a Payclave secret key. Never expose `sk_test_...` or `sk_live_...` keys in browser code.
+
+Package name: [`@payclave/sdk-server`](https://www.npmjs.com/package/@payclave/sdk-server).
+
+## Install
+
+```bash
+npm install @payclave/sdk-server
+# or
+bun add @payclave/sdk-server
+```
+
+## Create a checkout session
+
+```ts
+import { createPayclaveServerClient } from "@payclave/sdk-server"
+
+const payclave = createPayclaveServerClient({
+  secretKey: process.env.PAYCLAVE_SECRET_KEY!,
+})
+
+export async function POST(request: Request) {
+  const order = await request.json()
+
+  const session = await payclave.createCheckoutSession({
+    amount: order.total,
+    externalReference: order.id,
+    customerEmail: order.customerEmail,
+    successUrl: `https://merchant.example/orders/${order.id}/success`,
+    cancelUrl: "https://merchant.example/cart",
+    metadata: {
+      cartId: order.cartId,
+    },
+    idempotencyKey: order.id,
+  })
+
+  return Response.json({ checkoutUrl: session.checkoutUrl })
+}
+```
+
+## API
+
+### `createPayclaveServerClient(options)`
+
+| Option       | Type                      | Description                                                       |
+| ------------ | ------------------------- | ----------------------------------------------------------------- |
+| `secretKey`  | `string`                  | `sk_test_...` or `sk_live_...`. Required.                         |
+| `apiBaseUrl` | `string`                  | Override the API base URL. Defaults to `https://api.payclave.com`. |
+| `fetcher`    | `(url, init) => Response` | Custom fetch implementation for tests or custom runtimes.         |
+| `timeoutMs`  | `number`                  | Per-request timeout.                                              |
+
+Returns typed helpers:
+
+- `createCheckoutSession(input)`
+- `getCheckoutSession(id)`
+- `createInvoice(input)`
+- `getInvoice(id)`
+- `getPayment(id)`
+- `createWebhookEndpoint(input)`
+- `createTestWebhook(input)`
+- `listWebhookDeliveries(input?)`
+
+### Authentication
+
+This SDK is for backend code only and sends `Authorization: Bearer sk_test_...` or `Authorization: Bearer sk_live_...` on every request. Use publishable `pk_test_...` or `pk_live_...` keys only with browser checkout integrations.
+
+### Checkout session input
+
+| Field              | Type          | Description                                                                  |
+| ------------------ | ------------- | ---------------------------------------------------------------------------- |
+| `amount`           | `string`      | Positive USDT decimal with up to 6 fractional digits, e.g. `"25.00"`.        |
+| `externalReference` | `string?`     | Your order reference.                                                        |
+| `customerEmail`    | `string?`     | Customer email for checkout records.                                         |
+| `successUrl`       | `string?`     | URL to return to after payment.                                              |
+| `cancelUrl`        | `string?`     | URL to return to when checkout is cancelled.                                 |
+| `metadata`         | `object?`     | Merchant-defined metadata.                                                   |
+| `expiresInMinutes` | `number?`     | Checkout expiry, 5 to 1440 minutes.                                          |
+| `idempotencyKey`   | `string?`     | Sent as `Idempotency-Key`; reuse only for retries of the same request.       |
+| `signal`           | `AbortSignal?` | Cancel the request.                                                          |
+
+### Invoice input
+
+`createInvoice` accepts `amount`, `externalReference`, `metadata`, `expiresInMinutes`, `idempotencyKey`, and `signal`. Reuse the same `idempotencyKey` only when retrying the same invoice creation request after a timeout, network failure, `RATE_LIMIT_EXCEEDED`, or 5xx response.
+
+### Webhook endpoints
+
+`createWebhookEndpoint` accepts a `url`, optional `eventTypes`, and `signal`. Supported event types are exported as `PAYCLAVE_WEBHOOK_EVENT_TYPES` and currently include `invoice.paid`, `invoice.expired`, `payment.failed`, `payment.underpaid`, and `payment.overpaid`.
+
+Payclave returns the endpoint `signingSecret` once when the endpoint is created. Store it securely and use it to verify incoming webhook deliveries.
+
+## Webhook signatures
+
+Verify Payclave webhooks against the exact raw request body:
+
+```ts
+import { constructPayclaveWebhookEvent } from "@payclave/sdk-server"
+
+export async function POST(request: Request) {
+  const rawBody = await request.text()
+  const signature = request.headers.get("X-Payclave-Signature") ?? ""
+
+  const event = constructPayclaveWebhookEvent({
+    payload: rawBody,
+    signature,
+    secret: process.env.PAYCLAVE_WEBHOOK_SECRET!,
+  })
+
+  if (event.type === "invoice.paid") {
+    // Fulfill the order referenced by event.data.
+  }
+
+  return new Response(null, { status: 204 })
+}
+```
+
+`constructPayclaveWebhookEvent` throws `PayclaveError` when the signature, timestamp, or payload is invalid. Use `verifyPayclaveWebhookSignature` when you only need a boolean.
+
+Webhook deliveries include `X-Payclave-Signature`, `X-Payclave-Timestamp`, `X-Payclave-Delivery`, and `X-Payclave-Event` headers. The signature format is `t=<unix_timestamp>,v1=<hex_hmac_sha256>`.
+
+## Errors
+
+All client- and server-side failures throw a `PayclaveError`:
+
+```ts
+import { PayclaveError } from "@payclave/sdk-server"
+
+try {
+  await payclave.createCheckoutSession({ amount: "25.00" })
+} catch (err) {
+  if (err instanceof PayclaveError) {
+    err.code
+    err.status
+    err.requestId
+    err.details
+    err.cause
+  }
+}
+```
+
+Built-in client codes include `INVALID_SECRET_KEY`, `INVALID_API_BASE_URL`, `INVALID_TIMEOUT`, `INVALID_ID`, `INVALID_AMOUNT`, `INVALID_EXPIRY`, `INVALID_METADATA`, `INVALID_IDEMPOTENCY_KEY`, `INVALID_LIMIT`, `INVALID_WEBHOOK_URL`, `INVALID_REQUEST_BODY`, `INVALID_RESPONSE`, `NETWORK_ERROR`, `TIMEOUT`, `ABORTED`, and webhook verification errors. Server-supplied API codes are passed through unchanged.
+
+The package exports typed error-code lists for exhaustive handling and autocomplete:
+
+- `PAYCLAVE_API_ERROR_CODES`
+- `PAYCLAVE_SERVER_SDK_ERROR_CODES`
+- `PAYCLAVE_WEBHOOK_VERIFICATION_ERROR_CODES`
+- `PayclaveApiErrorCode`
+- `PayclaveServerSdkErrorCode`
+- `PayclaveWebhookVerificationErrorCode`
+- `PayclaveErrorCode`
+
+## SDK identification
+
+Every request includes `X-Payclave-Client: payclave-sdk-server/<version>` so the API can correlate bug reports to SDK versions.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).