@orcarail/node 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 OrcaRail
+
+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,235 @@
+# OrcaRail Node.js SDK
+
+[![npm version](https://badge.fury.io/js/%40orcarail%2Fnode.svg)](https://badge.fury.io/js/%40orcarail%2Fnode)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/orcarail/orcarail-node/workflows/CI/badge.svg)](https://github.com/orcarail/orcarail-node/actions)
+
+Official Node.js SDK for [OrcaRail](https://orcarail.com) - Accept crypto payments with Payment Intents.
+
+## Features
+
+- ✅ **Payment Intents** - Create, retrieve, confirm, and update payment intents
+- ✅ **Webhook Verification** - Secure webhook signature verification
+- ✅ **TypeScript Support** - Full TypeScript definitions included
+- ✅ **Zero Dependencies** - Uses native Node.js APIs (Node 18+)
+- ✅ **Dual Package** - Supports both ESM and CommonJS
+
+## Installation
+
+```bash
+npm install @orcarail/node
+```
+
+or
+
+```bash
+yarn add @orcarail/node
+```
+
+or
+
+```bash
+pnpm add @orcarail/node
+```
+
+## Quick Start
+
+```typescript
+import OrcaRail from '@orcarail/node';
+
+const orcarail = new OrcaRail('ak_live_xxx', 'sk_live_xxx');
+
+// Create a payment intent
+const intent = await orcarail.paymentIntents.create({
+  amount: '100.00',
+  currency: 'usd',
+  payment_method_types: ['crypto'],
+  tokenId: 1,
+  networkId: 1,
+  return_url: 'https://merchant.example.com/return',
+});
+
+console.log('Payment Intent ID:', intent.id);
+console.log('Client Secret:', intent.client_secret);
+```
+
+## API Reference
+
+### Payment Intents
+
+#### Create a Payment Intent
+
+```typescript
+const intent = await orcarail.paymentIntents.create({
+  amount: '100.00',
+  currency: 'usd',
+  payment_method_types: ['crypto'],
+  tokenId: 1,
+  networkId: 1,
+  return_url: 'https://merchant.example.com/return',
+  cancel_url: 'https://merchant.example.com/cancel', // optional
+  description: 'Payment for services', // optional
+  metadata: { order_id: '12345' }, // optional
+  expires_at: '2024-12-31T23:59:59Z', // optional
+});
+```
+
+#### Retrieve a Payment Intent
+
+```typescript
+const intent = await orcarail.paymentIntents.retrieve(
+  'pi_1234567890',
+  'pi_1234567890_secret_abc123'
+);
+```
+
+#### Confirm a Payment Intent
+
+```typescript
+const intent = await orcarail.paymentIntents.confirm('pi_1234567890', {
+  client_secret: 'pi_1234567890_secret_abc123',
+  return_url: 'https://merchant.example.com/return', // optional
+});
+```
+
+#### Update a Payment Intent
+
+```typescript
+const intent = await orcarail.paymentIntents.update('pi_1234567890', {
+  amount: '200.00',
+  description: 'Updated description',
+  metadata: { order_id: '67890' },
+});
+```
+
+### Webhooks
+
+#### Verify Webhook Signature
+
+```typescript
+import express from 'express';
+
+const app = express();
+
+app.post('/webhooks/orcarail', express.raw({ type: 'application/json' }), (req, res) => {
+  const signature = req.headers['x-webhook-signature'] as string;
+  const webhookSecret = process.env.ORCARAIL_WEBHOOK_SECRET!;
+
+  try {
+    const event = orcarail.webhooks.constructEvent(
+      req.body,
+      signature,
+      webhookSecret
+    );
+
+    // Handle the event
+    switch (event.type) {
+      case 'payment_intent.succeeded':
+        console.log('Payment succeeded:', event.data.object.id);
+        // Fulfill order, send confirmation email, etc.
+        break;
+      case 'payment_intent.processing':
+        console.log('Payment processing:', event.data.object.id);
+        break;
+      case 'payment_intent.canceled':
+        console.log('Payment canceled:', event.data.object.id);
+        break;
+    }
+
+    res.json({ received: true });
+  } catch (error) {
+    console.error('Webhook signature verification failed:', error);
+    res.status(400).json({ error: 'Invalid signature' });
+  }
+});
+```
+
+#### Verify Signature (Boolean)
+
+```typescript
+const isValid = orcarail.webhooks.verifySignature(
+  rawBody,
+  signature,
+  webhookSecret
+);
+
+if (isValid) {
+  // Process webhook
+} else {
+  // Reject webhook
+}
+```
+
+## Configuration
+
+```typescript
+const orcarail = new OrcaRail('ak_live_xxx', 'sk_live_xxx', {
+  baseUrl: 'https://api.orcarail.com/api/v1', // optional
+  timeout: 30000, // optional, default: 30000ms
+});
+```
+
+## Error Handling
+
+The SDK throws typed errors that you can catch:
+
+```typescript
+import {
+  OrcaRailError,
+  OrcaRailAPIError,
+  OrcaRailAuthenticationError,
+  OrcaRailSignatureVerificationError,
+} from '@orcarail/node';
+
+try {
+  const intent = await orcarail.paymentIntents.create({...});
+} catch (error) {
+  if (error instanceof OrcaRailAuthenticationError) {
+    console.error('Invalid API credentials');
+  } else if (error instanceof OrcaRailAPIError) {
+    console.error('API error:', error.statusCode, error.message);
+  } else if (error instanceof OrcaRailError) {
+    console.error('SDK error:', error.message);
+  }
+}
+```
+
+## TypeScript
+
+The SDK is written in TypeScript and includes full type definitions:
+
+```typescript
+import type {
+  PaymentIntent,
+  PaymentIntentCreateParams,
+  WebhookEvent,
+  WebhookEventType,
+} from '@orcarail/node';
+```
+
+## Requirements
+
+- Node.js 18.0.0 or higher
+- An OrcaRail account with API keys
+
+## Examples
+
+See the [examples](./examples/) directory for complete examples:
+
+- [Create Payment Intent](./examples/create-payment.ts)
+- [Express Webhook Handler](./examples/webhook-express.ts)
+- [Next.js API Route](./examples/webhook-nextjs.ts)
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
+
+## License
+
+MIT License - see [LICENSE](./LICENSE) for details.
+
+## Support
+
+- [Documentation](https://docs.orcarail.com)
+- [GitHub Issues](https://github.com/orcarail/orcarail-node/issues)
+- [Email Support](mailto:support@orcarail.com)

package/dist/index.cjs

@@ -0,0 +1,398 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var crypto = require('crypto');
+
+// src/errors.ts
+var OrcaRailError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "OrcaRailError";
+    Error.captureStackTrace(this, this.constructor);
+  }
+};
+var OrcaRailAPIError = class extends OrcaRailError {
+  /**
+   * HTTP status code
+   */
+  statusCode;
+  /**
+   * Error type from the API response
+   */
+  type;
+  /**
+   * Additional error details from the API
+   */
+  details;
+  constructor(message, statusCode, type, details) {
+    super(message);
+    this.name = "OrcaRailAPIError";
+    this.statusCode = statusCode;
+    this.type = type;
+    this.details = details;
+  }
+};
+var OrcaRailAuthenticationError = class extends OrcaRailAPIError {
+  constructor(message = "Authentication failed. Please check your API key and secret.") {
+    super(message, 401, "authentication_error");
+    this.name = "OrcaRailAuthenticationError";
+  }
+};
+var OrcaRailSignatureVerificationError = class extends OrcaRailError {
+  /**
+   * The signature that was provided
+   */
+  signature;
+  constructor(message = "Webhook signature verification failed", signature) {
+    super(message);
+    this.name = "OrcaRailSignatureVerificationError";
+    this.signature = signature || "";
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.orcarail.com/api/v1";
+var DEFAULT_TIMEOUT = 3e4;
+var SDK_VERSION = "1.0.0";
+var HttpClient = class {
+  apiKey;
+  apiSecret;
+  baseUrl;
+  timeout;
+  constructor(apiKey, apiSecret, config) {
+    if (!apiKey || !apiSecret) {
+      throw new OrcaRailError("API key and secret are required");
+    }
+    this.apiKey = apiKey;
+    this.apiSecret = apiSecret;
+    this.baseUrl = config?.baseUrl || DEFAULT_BASE_URL;
+    this.timeout = config?.timeout || DEFAULT_TIMEOUT;
+  }
+  /**
+   * Create Basic Auth header from API key and secret
+   */
+  getAuthHeader() {
+    const credentials = Buffer.from(`${this.apiKey}:${this.apiSecret}`).toString(
+      "base64"
+    );
+    return `Basic ${credentials}`;
+  }
+  /**
+   * Build full URL from path
+   */
+  buildUrl(path) {
+    const cleanPath = path.startsWith("/") ? path.slice(1) : path;
+    return `${this.baseUrl}/${cleanPath}`;
+  }
+  /**
+   * Make an HTTP request with timeout and error handling
+   */
+  async request(method, path, body, requireAuth = true) {
+    const url = this.buildUrl(path);
+    const headers = {
+      "Content-Type": "application/json",
+      "User-Agent": `orcarail-node/${SDK_VERSION}`
+    };
+    if (requireAuth) {
+      headers["Authorization"] = this.getAuthHeader();
+    }
+    const options = {
+      method,
+      headers
+    };
+    if (body) {
+      options.body = JSON.stringify(body);
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    options.signal = controller.signal;
+    try {
+      const response = await fetch(url, options);
+      clearTimeout(timeoutId);
+      let responseData;
+      const contentType = response.headers.get("content-type");
+      if (contentType && contentType.includes("application/json")) {
+        responseData = await response.json();
+      } else {
+        responseData = await response.text();
+      }
+      if (!response.ok) {
+        const errorMessage = typeof responseData === "object" && responseData !== null && "message" in responseData ? String(responseData.message) : `API request failed with status ${response.status}`;
+        const errorType = typeof responseData === "object" && responseData !== null && "error" in responseData ? String(responseData.error) : void 0;
+        if (response.status === 401) {
+          throw new OrcaRailAuthenticationError(errorMessage);
+        }
+        throw new OrcaRailAPIError(
+          errorMessage,
+          response.status,
+          errorType,
+          responseData
+        );
+      }
+      return responseData;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof OrcaRailError) {
+        throw error;
+      }
+      if (error instanceof Error) {
+        if (error.name === "AbortError") {
+          throw new OrcaRailError(
+            `Request timeout after ${this.timeout}ms`
+          );
+        }
+        throw new OrcaRailError(`Request failed: ${error.message}`);
+      }
+      throw new OrcaRailError("An unknown error occurred");
+    }
+  }
+  /**
+   * GET request
+   */
+  async get(path, requireAuth = true) {
+    return this.request("GET", path, void 0, requireAuth);
+  }
+  /**
+   * POST request
+   */
+  async post(path, body, requireAuth = true) {
+    return this.request("POST", path, body, requireAuth);
+  }
+  /**
+   * PATCH request
+   */
+  async patch(path, body, requireAuth = true) {
+    return this.request("PATCH", path, body, requireAuth);
+  }
+  /**
+   * PUT request
+   */
+  async put(path, body, requireAuth = true) {
+    return this.request("PUT", path, body, requireAuth);
+  }
+  /**
+   * DELETE request
+   */
+  async delete(path, requireAuth = true) {
+    return this.request("DELETE", path, void 0, requireAuth);
+  }
+};
+
+// src/resources/checkout.ts
+var Checkout = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get checkout details by slug
+   *
+   * @param slug - Checkout slug from the payment link URL
+   * @returns Checkout details including payment intent
+   */
+  async get(slug) {
+    const path = `checkout/${encodeURIComponent(slug)}`;
+    return this.client.get(path, true);
+  }
+  /**
+   * Cancel payment intent by checkout slug
+   *
+   * @param slug - Checkout slug from the payment link URL
+   * @returns The canceled payment intent and optional cancel_url for redirect
+   */
+  async cancel(slug) {
+    const path = `checkout/${encodeURIComponent(slug)}/cancel`;
+    return this.client.post(path, {}, true);
+  }
+};
+
+// src/resources/payment-intents.ts
+var PaymentIntents = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Create a new Payment Intent
+   *
+   * @param params - Payment Intent creation parameters
+   * @returns The created Payment Intent
+   */
+  async create(params) {
+    const requestBody = {
+      ...params,
+      payment_method_types: params.payment_method_types && params.payment_method_types.length > 0 ? params.payment_method_types : ["crypto"]
+    };
+    return this.client.post(
+      "payment_intents",
+      requestBody,
+      true
+    );
+  }
+  /**
+   * Retrieve a Payment Intent by ID
+   *
+   * @param id - Payment Intent ID (e.g., "pi_1234567890")
+   * @returns The Payment Intent
+   */
+  async retrieve(id) {
+    const cleanId = id.startsWith("pi_") ? id : `pi_${id}`;
+    const path = `payment_intents/${cleanId}`;
+    return this.client.get(path, true);
+  }
+  /**
+   * Cancel a Payment Intent (API: POST /payment_intents/:id/cancel).
+   * Use when the user is redirected to your cancel_url (e.g. https://yourapp.com/cancel?payment_intent=pi_20)
+   * and you want to mark the intent as canceled on the backend.
+   *
+   * @param id - Payment Intent ID (e.g. "pi_20" or "20")
+   * @returns The canceled Payment Intent
+   *
+   * @example
+   * // When user lands on https://localhost:3001/cancel?payment_intent=pi_20
+   * const intent = await orcarail.paymentIntents.cancel('pi_20');
+   */
+  async cancel(id) {
+    const cleanId = id.startsWith("pi_") ? id : `pi_${id}`;
+    const path = `payment_intents/${cleanId}/cancel`;
+    return this.client.post(path, {}, true);
+  }
+  /**
+   * Confirm a Payment Intent (API: POST /payment_intents/:id/confirm).
+   * Redirects the customer to the hosted checkout page.
+   *
+   * @param id - Payment Intent ID (e.g. "pi_20" or "20")
+   * @param params - Confirmation parameters including client_secret and return_url
+   * @returns The confirmed Payment Intent
+   *
+   * @example
+   * const intent = await orcarail.paymentIntents.confirm('pi_20', {
+   *   client_secret: intent.client_secret,
+   *   return_url: 'https://yourapp.com/return',
+   * });
+   */
+  async confirm(id, params) {
+    const cleanId = id.startsWith("pi_") ? id : `pi_${id}`;
+    const path = `payment_intents/${cleanId}/confirm`;
+    return this.client.post(path, params, false);
+  }
+  /**
+   * Complete a Payment Intent (API: POST /payment_intents/:id/complete).
+   * Sets the intent to processing and fires the payment_intent.processing webhook.
+   * Use when the user is redirected to your success/return URL (e.g. https://yourapp.com/success?payment_intent=pi_34).
+   *
+   * @param id - Payment Intent ID (e.g. "pi_34" or "34")
+   * @returns The updated Payment Intent (status processing)
+   *
+   * @example
+   * // When user lands on https://localhost:3001/success?payment_intent=pi_34
+   * const intent = await orcarail.paymentIntents.complete('pi_34');
+   */
+  async complete(id) {
+    const cleanId = id.startsWith("pi_") ? id : `pi_${id}`;
+    const path = `payment_intents/${cleanId}/complete`;
+    return this.client.post(path, {}, true);
+  }
+  /**
+   * Update a Payment Intent
+   *
+   * @param id - Payment Intent ID
+   * @param params - Update parameters (all optional)
+   * @returns The updated Payment Intent
+   */
+  async update(id, params) {
+    const cleanId = id.startsWith("pi_") ? id : `pi_${id}`;
+    const path = `payment_intents/${cleanId}`;
+    return this.client.patch(path, params, true);
+  }
+};
+var Webhooks = class {
+  /**
+   * Verify webhook signature
+   *
+   * @param rawBody - Raw request body (string or Buffer)
+   * @param signature - Signature from x-webhook-signature header
+   * @param secret - Webhook secret (API key's secretHash)
+   * @returns True if signature is valid, false otherwise
+   */
+  verifySignature(rawBody, signature, secret) {
+    if (!signature || !secret) {
+      return false;
+    }
+    const bodyString = typeof rawBody === "string" ? rawBody : rawBody.toString("utf8");
+    const expectedSignature = crypto.createHmac("sha256", secret).update(bodyString).digest("hex");
+    const signatureBuffer = Buffer.from(signature, "hex");
+    const expectedBuffer = Buffer.from(expectedSignature, "hex");
+    if (signatureBuffer.length !== expectedBuffer.length) {
+      return false;
+    }
+    return crypto.timingSafeEqual(signatureBuffer, expectedBuffer);
+  }
+  /**
+   * Construct and verify a webhook event from raw body and signature
+   *
+   * @param rawBody - Raw request body (string or Buffer)
+   * @param signature - Signature from x-webhook-signature header
+   * @param secret - Webhook secret (API key's secretHash)
+   * @returns Parsed webhook event
+   * @throws OrcaRailSignatureVerificationError if signature is invalid
+   */
+  constructEvent(rawBody, signature, secret) {
+    if (!this.verifySignature(rawBody, signature, secret)) {
+      throw new OrcaRailSignatureVerificationError(
+        "Webhook signature verification failed. The signature does not match the expected signature.",
+        signature
+      );
+    }
+    const bodyString = typeof rawBody === "string" ? rawBody : rawBody.toString("utf8");
+    try {
+      const event = JSON.parse(bodyString);
+      return event;
+    } catch (error) {
+      throw new OrcaRailSignatureVerificationError(
+        `Failed to parse webhook body: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+};
+
+// src/index.ts
+var OrcaRail = class {
+  /**
+   * Payment Intents resource
+   */
+  paymentIntents;
+  /**
+   * Checkout resource (slug-based get/cancel)
+   */
+  checkout;
+  /**
+   * Webhooks utilities
+   */
+  webhooks;
+  client;
+  /**
+   * Create a new OrcaRail client instance
+   *
+   * @param apiKey - Your OrcaRail API key (e.g., "ak_live_xxx")
+   * @param apiSecret - Your OrcaRail API secret (e.g., "sk_live_xxx")
+   * @param config - Optional configuration
+   */
+  constructor(apiKey, apiSecret, config) {
+    this.client = new HttpClient(apiKey, apiSecret, config);
+    this.paymentIntents = new PaymentIntents(this.client);
+    this.checkout = new Checkout(this.client);
+    this.webhooks = new Webhooks();
+  }
+};
+var index_default = OrcaRail;
+
+exports.OrcaRail = OrcaRail;
+exports.OrcaRailAPIError = OrcaRailAPIError;
+exports.OrcaRailAuthenticationError = OrcaRailAuthenticationError;
+exports.OrcaRailError = OrcaRailError;
+exports.OrcaRailSignatureVerificationError = OrcaRailSignatureVerificationError;
+exports.default = index_default;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map