@saleslane/sdk 1.0.0

package/README.md

@@ -0,0 +1,57 @@
+# @saleslane/sdk
+
+JavaScript SDK for the Saleslane API. Handles RS256 JWT signing automatically.
+
+## Installation
+
+```bash
+npm install @saleslane/sdk
+```
+
+## Usage
+
+```js
+const { SaleslaneClient } = require('@saleslane/sdk');
+
+const client = new SaleslaneClient({
+  baseUrl: 'https://your-instance.saleslane.nl',
+  apiRecordId: process.env.SALESLANE_API_RECORD_ID,
+  privateKey: process.env.SALESLANE_PRIVATE_KEY,
+});
+
+const me = await client.getMe();
+console.log(me.data);
+```
+
+## Authentication
+
+Every request is signed with an RS256 JWT:
+
+- **GET** requests: params are signed and sent as `?signed=<jwt>`
+- **POST/PUT/PATCH/DELETE**: the body is signed and sent as the JWT string
+
+You need an API record ID and the matching RSA private key. Register the public key on the API record in Saleslane.
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `getMe()` | Get the authenticated API record |
+| `revokeMe()` | Deactivate the API record (irreversible) |
+| `getContactByPhone({ phoneNumber })` | Look up contacts by E.164 phone number |
+| `addTransactionTag({ referenceId, tag, ... })` | Add a tag to a subtransaction |
+| `listUsers()` | List all users |
+| `listTeams()` | List all teams |
+
+## Low-level Exports
+
+```js
+const { signPayload, createSignedHooks } = require('@saleslane/sdk');
+
+const token = signPayload(payload, privateKey, apiRecordId);
+const hooks = createSignedHooks(privateKey, apiRecordId);
+```
+
+## License
+
+ISC

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@saleslane/sdk",
+  "version": "1.0.0",
+  "description": "JavaScript SDK for the Saleslane API (RS256 signed requests)",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "jest __tests__/signing.test.js __tests__/client.test.js --verbose",
+    "test:integration": "bash test1.sh"
+  },
+  "keywords": [
+    "saleslane",
+    "sdk",
+    "api",
+    "rs256",
+    "jwt"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/saleslane/saleslane.git",
+    "directory": "packages/sdk"
+  },
+  "dependencies": {
+    "got": "^11.8.2",
+    "jsonwebtoken": "^9.0.0",
+    "uuid": "^8.3.2"
+  },
+  "license": "ISC"
+}

package/src/client.js

@@ -0,0 +1,140 @@
+const got = require('got');
+const { createSignedHooks } = require('./signing');
+
+/**
+ * @typedef {object} SaleslaneClientOptions
+ * @property {string} baseUrl      – Backend URL, e.g. "https://api.saleslane.com" or "http://localhost:4002".
+ * @property {string} apiRecordId  – The API record ID (24-char hex ObjectId or referenceId).
+ * @property {string} privateKey   – RSA private key in PEM format for RS256 signing.
+ */
+
+/**
+ * JavaScript SDK client for the Saleslane API.
+ *
+ * All requests are automatically signed with RS256 JWTs.
+ *
+ * @example
+ * const { SaleslaneClient } = require('@saleslane/sdk');
+ *
+ * const client = new SaleslaneClient({
+ *   baseUrl: 'https://api.saleslane.com',
+ *   apiRecordId: '64a1b2c3d4e5f6a7b8c9d0e1',
+ *   privateKey: process.env.API_PRIVATE_KEY,
+ * });
+ *
+ * const me = await client.getMe();
+ * console.log(me.data);
+ */
+class SaleslaneClient {
+  /**
+   * @param {SaleslaneClientOptions} options
+   */
+  constructor({ baseUrl, apiRecordId, privateKey }) {
+    if (!baseUrl) throw new Error('SaleslaneClient: baseUrl is required');
+    if (!apiRecordId) throw new Error('SaleslaneClient: apiRecordId is required');
+    if (!privateKey) throw new Error('SaleslaneClient: privateKey is required');
+
+    this._client = got.extend({
+      prefixUrl: `${baseUrl.replace(/\/+$/, '')}/api/v1`,
+      responseType: 'json',
+      hooks: createSignedHooks(privateKey, apiRecordId),
+    });
+  }
+
+  // ---------------------------------------------------------------------------
+  // API (self)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Get the authenticated API record.
+   * @returns {Promise<{data: {_id: string, title: string, description: string, exp: string}}>}
+   */
+  getMe() {
+    return this._client.get('api/me').json();
+  }
+
+  /**
+   * Revoke / deactivate the API record.
+   * @returns {Promise<{data: object}>}
+   */
+  revokeMe() {
+    return this._client.delete('api/me').json();
+  }
+
+  // ---------------------------------------------------------------------------
+  // Contact
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Look up contacts by E.164 phone number.
+   * Returns contacts with their transactions and subtransactions.
+   *
+   * @param {object} params
+   * @param {string} params.phoneNumber – E.164 formatted phone number, e.g. "+31612345678".
+   * @returns {Promise<{data: Array}>}
+   */
+  getContactByPhone({ phoneNumber }) {
+    return this._client.get('contact/by-phone', {
+      searchParams: { phoneNumber },
+    }).json();
+  }
+
+  // ---------------------------------------------------------------------------
+  // Transaction
+  // ---------------------------------------------------------------------------
+  /**
+   * Add a tag to a subtransaction by its friendly referenceId.
+   *
+   * The referenceId format is: the transaction referenceId + a 2-digit
+   * 1-based subtransaction index (e.g. "2607700101").
+   *
+   * @param {object} params
+   * @param {string} params.referenceId – Full referenceId including subtransaction suffix.
+   * @param {string} params.tag         – Tag name.
+   * @param {string} [params.description]
+   * @param {string} [params.color]     – Hex color, e.g. "#6366f1".
+   * @param {string} [params.labelType] – e.g. "info".
+   * @param {string} [params.value]
+   * @param {string} [params.date]      – ISO 8601 date string.
+   * @returns {Promise<{data: object}>}
+   */
+  addTransactionTag({ referenceId, tag, description, color, labelType, value, date }) {
+    return this._client.post('transaction/transaction-tag', {
+      json: {
+        referenceId,
+        tag,
+        ...(description !== undefined && { description }),
+        ...(color !== undefined && { color }),
+        ...(labelType !== undefined && { labelType }),
+        ...(value !== undefined && { value }),
+        ...(date !== undefined && { date }),
+      },
+    }).json();
+  }
+
+  // ---------------------------------------------------------------------------
+  // User
+  // ---------------------------------------------------------------------------
+
+  /**
+   * List all users.
+   * @returns {Promise<{data: Array<{_id: string, email: string, first_name: string, last_name: string, nickName?: string, team?: string, deleted?: boolean}>}>}
+   */
+  listUsers() {
+    return this._client.get('user').json();
+  }
+
+  // ---------------------------------------------------------------------------
+  // Team
+  // ---------------------------------------------------------------------------
+
+  /**
+   * List all teams.
+   * @returns {Promise<{data: Array<{_id: string, name: string, deleted?: boolean}>}>}
+   */
+  listTeams() {
+    return this._client.get('team').json();
+  }
+}
+
+module.exports = { SaleslaneClient };

package/src/index.js

@@ -0,0 +1,8 @@
+const { SaleslaneClient } = require('./client');
+const { signPayload, createSignedHooks } = require('./signing');
+
+module.exports = {
+  SaleslaneClient,
+  signPayload,
+  createSignedHooks,
+};

package/src/signing.js

@@ -0,0 +1,62 @@
+const jwt = require('jsonwebtoken');
+const { v4: uuidv4 } = require('uuid');
+
+/**
+ * Sign a payload using RS256 for the Saleslane API.
+ *
+ * @param {object} data    – The actual query params (GET) or body (POST/PUT/PATCH/DELETE).
+ * @param {string} privateKey – RSA private key in PEM format.
+ * @param {string} subject – API record ID (the `sub` claim).
+ * @returns {string} Signed JWT.
+ */
+function signPayload(data, privateKey, subject) {
+  return jwt.sign({ data }, privateKey, {
+    algorithm: 'RS256',
+    expiresIn: 900,
+    subject,
+    jwtid: uuidv4(),
+  });
+}
+
+/**
+ * Create `got` hooks that transparently sign every request.
+ *
+ * - GET requests: query params are wrapped in a JWT and sent as `?signed=<token>`.
+ * - POST/PUT/PATCH/DELETE: the JSON body is wrapped in a JWT and sent as the raw body.
+ *
+ * @param {string} privateKey  – RSA private key in PEM format.
+ * @param {string} apiRecordId – The API record ID used as JWT `sub`.
+ * @returns {object} Hooks object for `got.extend()`.
+ */
+function createSignedHooks(privateKey, apiRecordId) {
+  return {
+    init: [
+      (plain) => {
+        if (['get'].includes(plain.method)) {
+          const signed = signPayload(plain.searchParams || {}, privateKey, apiRecordId);
+          plain.searchParams = { signed };
+        }
+        if (['post', 'put', 'delete', 'patch'].includes(plain.method)) {
+          const signed = signPayload(plain.json || {}, privateKey, apiRecordId);
+          plain.json = signed;
+        }
+      },
+    ],
+    beforeError: [
+      (error) => {
+        const { response, options } = error;
+        if (response && response.body && options) {
+          error.name = 'SaleslaneApiError';
+          error.message = `${options.method} ${options.url.href} -> ${response.statusCode}\n${
+            typeof response.body === 'object'
+              ? JSON.stringify(response.body, null, 2)
+              : response.body
+          }`;
+        }
+        return error;
+      },
+    ],
+  };
+}
+
+module.exports = { signPayload, createSignedHooks };