@frihet/sdk 1.0.0

package/README.md

@@ -0,0 +1,131 @@
+# @frihet/sdk
+
+Official TypeScript SDK for the [Frihet](https://frihet.io) API. AI-native business management.
+
+## Install
+
+```bash
+npm install @frihet/sdk
+```
+
+## Quick start
+
+```typescript
+import Frihet from '@frihet/sdk';
+
+const frihet = new Frihet({ apiKey: 'fri_...' });
+
+// Create an invoice
+const invoice = await frihet.invoices.create({
+  clientName: 'Acme Corp',
+  items: [{ description: 'Consulting', quantity: 10, unitPrice: 150 }],
+});
+
+// List overdue invoices
+const overdue = await frihet.invoices.list({ status: 'overdue' });
+
+// Mark as paid
+await frihet.invoices.markPaid(invoice.id);
+
+// Send by email
+await frihet.invoices.send(invoice.id, { recipientEmail: 'billing@acme.com' });
+
+// Download PDF
+const pdf = await frihet.invoices.pdf(invoice.id);
+```
+
+## Resources
+
+| Resource | Methods |
+|----------|---------|
+| `frihet.invoices` | `list`, `retrieve`, `create`, `update`, `del`, `search`, `markPaid`, `send`, `pdf`, `createBatch` |
+| `frihet.expenses` | `list`, `retrieve`, `create`, `update`, `del`, `search`, `createBatch` |
+| `frihet.clients` | `list`, `retrieve`, `create`, `update`, `del`, `search` |
+| `frihet.vendors` | `list`, `retrieve`, `create`, `update`, `del`, `search` |
+| `frihet.products` | `list`, `retrieve`, `create`, `update`, `del`, `search` |
+| `frihet.quotes` | `list`, `retrieve`, `create`, `update`, `del`, `search`, `send`, `pdf` |
+| `frihet.webhooks` | `list`, `retrieve`, `create`, `update`, `del` |
+| `frihet.intelligence` | `context`, `summary`, `monthly`, `quarterly` |
+
+## Intelligence
+
+```typescript
+// Full business context (one call for AI agents)
+const ctx = await frihet.intelligence.context();
+
+// Monthly P&L with tax liability
+const march = await frihet.intelligence.monthly('2026-03');
+
+// Quarterly tax prep (Modelo 303/130)
+const q1 = await frihet.intelligence.quarterly('2026-Q1');
+
+// Financial summary with date range
+const ytd = await frihet.intelligence.summary({ from: '2026-01-01', to: '2026-12-31' });
+```
+
+## Error handling
+
+```typescript
+import Frihet, { RateLimitError, NotFoundError, ValidationError } from '@frihet/sdk';
+
+try {
+  await frihet.invoices.retrieve('nonexistent');
+} catch (err) {
+  if (err instanceof NotFoundError) {
+    console.log('Invoice not found');
+  } else if (err instanceof RateLimitError) {
+    console.log(`Retry after ${err.retryAfter}s`);
+  } else if (err instanceof ValidationError) {
+    console.log('Validation:', err.details);
+  }
+}
+```
+
+## Webhook verification
+
+```typescript
+import { Webhooks } from '@frihet/sdk';
+
+const isValid = Webhooks.verifySignature(
+  rawBody,
+  req.headers['x-frihet-signature'],
+  webhookSecret,
+);
+```
+
+## Configuration
+
+```typescript
+const frihet = new Frihet({
+  apiKey: 'fri_...',
+  baseUrl: 'https://api.frihet.io/v1', // default
+  timeout: 30000, // 30s default
+});
+
+// Per-request options
+await frihet.invoices.create(data, {
+  idempotencyKey: 'unique-key-123',
+  timeout: 60000,
+});
+```
+
+## Features
+
+- Full TypeScript types with autocompletion
+- Automatic retry on rate limits (429) and server errors (5xx)
+- Exponential backoff with configurable retries
+- Idempotency key support for safe retries
+- Dual CJS/ESM output
+- Zero runtime dependencies
+- Request ID tracking on errors
+- HMAC webhook signature verification
+
+## Links
+
+- [API Documentation](https://docs.frihet.io/desarrolladores/api-rest)
+- [MCP Server](https://www.npmjs.com/package/@frihet/mcp-server)
+- [CLI](https://www.npmjs.com/package/frihet)
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,542 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  APIError: () => APIError,
+  AuthenticationError: () => AuthenticationError,
+  Clients: () => Clients,
+  Expenses: () => Expenses,
+  Frihet: () => Frihet,
+  FrihetError: () => FrihetError,
+  Intelligence: () => Intelligence,
+  Invoices: () => Invoices,
+  NotFoundError: () => NotFoundError,
+  Products: () => Products,
+  Quotes: () => Quotes,
+  RateLimitError: () => RateLimitError,
+  TimeoutError: () => TimeoutError,
+  ValidationError: () => ValidationError,
+  Vendors: () => Vendors,
+  Webhooks: () => Webhooks,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/error.ts
+var FrihetError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "FrihetError";
+  }
+};
+var APIError = class extends FrihetError {
+  status;
+  code;
+  requestId;
+  constructor(status, code, message, requestId) {
+    super(message);
+    this.name = "APIError";
+    this.status = status;
+    this.code = code;
+    this.requestId = requestId;
+  }
+};
+var AuthenticationError = class extends APIError {
+  constructor(message = "Invalid or missing API key") {
+    super(401, "authentication_error", message);
+    this.name = "AuthenticationError";
+  }
+};
+var NotFoundError = class extends APIError {
+  constructor(message = "Resource not found") {
+    super(404, "not_found", message);
+    this.name = "NotFoundError";
+  }
+};
+var ValidationError = class extends APIError {
+  details;
+  constructor(message, details) {
+    super(400, "validation_error", message);
+    this.name = "ValidationError";
+    this.details = details;
+  }
+};
+var RateLimitError = class extends APIError {
+  retryAfter;
+  constructor(retryAfter) {
+    super(429, "rate_limit_exceeded", "Rate limit exceeded. Please retry later.");
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+var TimeoutError = class extends FrihetError {
+  constructor(timeoutMs) {
+    super(`Request timed out after ${timeoutMs}ms`);
+    this.name = "TimeoutError";
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.frihet.io/v1";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var MAX_RETRIES = 3;
+var BASE_RETRY_DELAY_MS = 1e3;
+var SDK_VERSION = "1.0.0";
+var RETRYABLE_STATUS_CODES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+var HttpClient = class {
+  apiKey;
+  baseUrl;
+  timeout;
+  constructor(opts) {
+    if (!opts.apiKey) {
+      throw new Error("apiKey is required. Get one at https://app.frihet.io/settings/security");
+    }
+    this.apiKey = opts.apiKey;
+    this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.timeout = opts.timeout ?? DEFAULT_TIMEOUT_MS;
+  }
+  get defaultHeaders() {
+    return {
+      "X-API-Key": this.apiKey,
+      "Content-Type": "application/json",
+      "Accept": "application/json",
+      "User-Agent": `@frihet/sdk/${SDK_VERSION} (node)`
+    };
+  }
+  async get(path, query, opts) {
+    return this.request("GET", path, void 0, query, opts);
+  }
+  async post(path, body, opts) {
+    return this.request("POST", path, body, void 0, opts);
+  }
+  async patch(path, body, opts) {
+    return this.request("PATCH", path, body, void 0, opts);
+  }
+  async del(path, opts) {
+    return this.request("DELETE", path, void 0, void 0, opts);
+  }
+  async getPage(path, query, opts) {
+    const raw = await this.requestRaw("GET", path, void 0, query, opts);
+    const body = await raw.json();
+    const page = this.extractPageFromEnvelope(body);
+    if (!page) {
+      throw new APIError(200, "invalid_response", "Expected paginated response with data array", this.extractRequestId(raw));
+    }
+    return page;
+  }
+  async getRaw(path, opts) {
+    const response = await this.requestRaw("GET", path, void 0, void 0, opts);
+    return response.arrayBuffer();
+  }
+  async request(method, path, body, query, opts) {
+    const response = await this.requestRaw(method, path, body, query, opts);
+    if (response.status === 204) {
+      return void 0;
+    }
+    const json = await response.json();
+    return this.unwrapEnvelope(json);
+  }
+  async requestRaw(method, path, body, query, opts, retryCount = 0) {
+    const url = new URL(`${this.baseUrl}${path}`);
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
+        if (value !== void 0) url.searchParams.set(key, String(value));
+      }
+    }
+    const headers = { ...this.defaultHeaders };
+    if (opts?.idempotencyKey) {
+      headers["Idempotency-Key"] = opts.idempotencyKey;
+    }
+    const controller = new AbortController();
+    const timeoutMs = opts?.timeout ?? this.timeout;
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+      response = await fetch(url.toString(), {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : void 0,
+        signal: opts?.signal ?? controller.signal
+      });
+    } catch (err) {
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new TimeoutError(timeoutMs);
+      }
+      if (retryCount < MAX_RETRIES) {
+        const delayMs = BASE_RETRY_DELAY_MS * Math.pow(2, retryCount);
+        await new Promise((r) => setTimeout(r, delayMs));
+        return this.requestRaw(method, path, body, query, opts, retryCount + 1);
+      }
+      throw err;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+    if (RETRYABLE_STATUS_CODES.has(response.status) && retryCount < MAX_RETRIES) {
+      if (response.status === 429) {
+        const retryAfter = response.headers.get("Retry-After");
+        const delayMs = retryAfter ? parseInt(retryAfter, 10) * 1e3 : BASE_RETRY_DELAY_MS * Math.pow(2, retryCount);
+        await new Promise((r) => setTimeout(r, delayMs));
+      } else {
+        const delayMs = BASE_RETRY_DELAY_MS * Math.pow(2, retryCount);
+        await new Promise((r) => setTimeout(r, delayMs));
+      }
+      return this.requestRaw(method, path, body, query, opts, retryCount + 1);
+    }
+    if (response.status === 429) {
+      const retryAfter = response.headers.get("Retry-After");
+      throw new RateLimitError(retryAfter ? parseInt(retryAfter, 10) : void 0);
+    }
+    if (!response.ok) {
+      const requestId = this.extractRequestId(response);
+      let errorBody;
+      try {
+        const json = await response.json();
+        errorBody = json.error ? json : json.data ?? json;
+      } catch {
+        errorBody = { error: `http_${response.status}`, message: response.statusText };
+      }
+      throw this.buildError(response.status, errorBody, requestId);
+    }
+    return response;
+  }
+  /**
+   * Unwrap the API response envelope.
+   * API returns: { data: T, meta: {...} } for single resources
+   *              { data: T[], total, limit, offset, meta: {...} } for lists
+   */
+  unwrapEnvelope(json) {
+    if (json && typeof json === "object" && "data" in json) {
+      const obj = json;
+      if ("total" in obj && "limit" in obj) {
+        return json;
+      }
+      return obj.data;
+    }
+    return json;
+  }
+  extractPageFromEnvelope(json) {
+    if (!json || typeof json !== "object") return null;
+    const obj = json;
+    if (Array.isArray(obj.data) && "total" in obj) {
+      return { data: obj.data, total: obj.total, limit: obj.limit, offset: obj.offset };
+    }
+    return null;
+  }
+  extractRequestId(response) {
+    return response.headers.get("X-Request-Id") ?? void 0;
+  }
+  buildError(status, body, requestId) {
+    switch (status) {
+      case 401:
+        return new AuthenticationError(body.message);
+      case 404:
+        return new NotFoundError(body.message);
+      case 400:
+      case 422:
+        return new ValidationError(body.message ?? body.error, body.details);
+      case 429:
+        return new RateLimitError();
+      default:
+        return new APIError(status, body.error, body.message ?? body.error, requestId);
+    }
+  }
+};
+
+// src/resources/invoices.ts
+var enc = encodeURIComponent;
+var Invoices = class {
+  constructor(_client) {
+    this._client = _client;
+  }
+  list(params, opts) {
+    return this._client.getPage("/invoices", params, opts);
+  }
+  retrieve(id, opts) {
+    return this._client.get(`/invoices/${enc(id)}`, void 0, opts);
+  }
+  create(params, opts) {
+    return this._client.post("/invoices", params, opts);
+  }
+  update(id, params, opts) {
+    return this._client.patch(`/invoices/${enc(id)}`, params, opts);
+  }
+  del(id, opts) {
+    return this._client.del(`/invoices/${enc(id)}`, opts);
+  }
+  search(query, params, opts) {
+    return this._client.getPage("/invoices", { q: query, ...params }, opts);
+  }
+  markPaid(id, paidDate, opts) {
+    return this._client.post(`/invoices/${enc(id)}/paid`, paidDate ? { paidDate } : void 0, opts);
+  }
+  send(id, params, opts) {
+    return this._client.post(`/invoices/${enc(id)}/send`, params, opts);
+  }
+  pdf(id, opts) {
+    return this._client.getRaw(`/invoices/${enc(id)}/pdf`, opts);
+  }
+  createBatch(items, opts) {
+    return this._client.post("/invoices/batch", items, opts);
+  }
+};
+
+// src/resources/expenses.ts
+var enc2 = encodeURIComponent;
+var Expenses = class {
+  constructor(_client) {
+    this._client = _client;
+  }
+  list(params, opts) {
+    return this._client.getPage("/expenses", params, opts);
+  }
+  retrieve(id, opts) {
+    return this._client.get(`/expenses/${enc2(id)}`, void 0, opts);
+  }
+  create(params, opts) {
+    return this._client.post("/expenses", params, opts);
+  }
+  update(id, params, opts) {
+    return this._client.patch(`/expenses/${enc2(id)}`, params, opts);
+  }
+  del(id, opts) {
+    return this._client.del(`/expenses/${enc2(id)}`, opts);
+  }
+  search(query, params, opts) {
+    return this._client.getPage("/expenses", { q: query, ...params }, opts);
+  }
+  createBatch(items, opts) {
+    return this._client.post("/expenses/batch", items, opts);
+  }
+};
+
+// src/resources/clients.ts
+var enc3 = encodeURIComponent;
+var Clients = class {
+  constructor(_client) {
+    this._client = _client;
+  }
+  list(params, opts) {
+    return this._client.getPage("/clients", params, opts);
+  }
+  retrieve(id, opts) {
+    return this._client.get(`/clients/${enc3(id)}`, void 0, opts);
+  }
+  create(params, opts) {
+    return this._client.post("/clients", params, opts);
+  }
+  update(id, params, opts) {
+    return this._client.patch(`/clients/${enc3(id)}`, params, opts);
+  }
+  del(id, opts) {
+    return this._client.del(`/clients/${enc3(id)}`, opts);
+  }
+  search(query, params, opts) {
+    return this._client.getPage("/clients", { q: query, ...params }, opts);
+  }
+};
+
+// src/resources/products.ts
+var enc4 = encodeURIComponent;
+var Products = class {
+  constructor(_client) {
+    this._client = _client;
+  }
+  list(params, opts) {
+    return this._client.getPage("/products", params, opts);
+  }
+  retrieve(id, opts) {
+    return this._client.get(`/products/${enc4(id)}`, void 0, opts);
+  }
+  create(params, opts) {
+    return this._client.post("/products", params, opts);
+  }
+  update(id, params, opts) {
+    return this._client.patch(`/products/${enc4(id)}`, params, opts);
+  }
+  del(id, opts) {
+    return this._client.del(`/products/${enc4(id)}`, opts);
+  }
+  search(query, params, opts) {
+    return this._client.getPage("/products", { q: query, ...params }, opts);
+  }
+};
+
+// src/resources/quotes.ts
+var enc5 = encodeURIComponent;
+var Quotes = class {
+  constructor(_client) {
+    this._client = _client;
+  }
+  list(params, opts) {
+    return this._client.getPage("/quotes", params, opts);
+  }
+  retrieve(id, opts) {
+    return this._client.get(`/quotes/${enc5(id)}`, void 0, opts);
+  }
+  create(params, opts) {
+    return this._client.post("/quotes", params, opts);
+  }
+  update(id, params, opts) {
+    return this._client.patch(`/quotes/${enc5(id)}`, params, opts);
+  }
+  del(id, opts) {
+    return this._client.del(`/quotes/${enc5(id)}`, opts);
+  }
+  search(query, params, opts) {
+    return this._client.getPage("/quotes", { q: query, ...params }, opts);
+  }
+  pdf(id, opts) {
+    return this._client.getRaw(`/quotes/${enc5(id)}/pdf`, opts);
+  }
+  send(id, params, opts) {
+    return this._client.post(`/quotes/${enc5(id)}/send`, params, opts);
+  }
+};
+
+// src/resources/vendors.ts
+var enc6 = encodeURIComponent;
+var Vendors = class {
+  constructor(_client) {
+    this._client = _client;
+  }
+  list(params, opts) {
+    return this._client.getPage("/vendors", params, opts);
+  }
+  retrieve(id, opts) {
+    return this._client.get(`/vendors/${enc6(id)}`, void 0, opts);
+  }
+  create(params, opts) {
+    return this._client.post("/vendors", params, opts);
+  }
+  update(id, params, opts) {
+    return this._client.patch(`/vendors/${enc6(id)}`, params, opts);
+  }
+  del(id, opts) {
+    return this._client.del(`/vendors/${enc6(id)}`, opts);
+  }
+  search(query, params, opts) {
+    return this._client.getPage("/vendors", { q: query, ...params }, opts);
+  }
+};
+
+// src/resources/webhooks.ts
+var import_node_crypto = require("crypto");
+var enc7 = encodeURIComponent;
+var Webhooks = class {
+  constructor(_client) {
+    this._client = _client;
+  }
+  list(params, opts) {
+    return this._client.getPage("/webhooks", params, opts);
+  }
+  retrieve(id, opts) {
+    return this._client.get(`/webhooks/${enc7(id)}`, void 0, opts);
+  }
+  create(params, opts) {
+    return this._client.post("/webhooks", params, opts);
+  }
+  update(id, params, opts) {
+    return this._client.patch(`/webhooks/${enc7(id)}`, params, opts);
+  }
+  del(id, opts) {
+    return this._client.del(`/webhooks/${enc7(id)}`, opts);
+  }
+  /**
+   * Verify a webhook signature. Use this in your webhook handler to confirm
+   * the payload was sent by Frihet.
+   *
+   * @param payload - Raw request body (string or Buffer)
+   * @param signature - Value of the X-Frihet-Signature header
+   * @param secret - Your webhook secret
+   */
+  static verifySignature(payload, signature, secret) {
+    const expected = `sha256=${(0, import_node_crypto.createHmac)("sha256", secret).update(payload).digest("hex")}`;
+    if (expected.length !== signature.length) return false;
+    let mismatch = 0;
+    for (let i = 0; i < expected.length; i++) {
+      mismatch |= expected.charCodeAt(i) ^ signature.charCodeAt(i);
+    }
+    return mismatch === 0;
+  }
+};
+
+// src/resources/intelligence.ts
+var Intelligence = class {
+  constructor(_client) {
+    this._client = _client;
+  }
+  context(opts) {
+    return this._client.get("/context", void 0, opts);
+  }
+  summary(params, opts) {
+    return this._client.get("/summary", params, opts);
+  }
+  monthly(month, opts) {
+    return this._client.get("/monthly", month ? { month } : void 0, opts);
+  }
+  quarterly(quarter, opts) {
+    return this._client.get("/quarterly", quarter ? { quarter } : void 0, opts);
+  }
+};
+
+// src/index.ts
+var Frihet = class {
+  invoices;
+  expenses;
+  clients;
+  vendors;
+  products;
+  quotes;
+  webhooks;
+  intelligence;
+  constructor(opts) {
+    const client = new HttpClient(opts);
+    this.invoices = new Invoices(client);
+    this.expenses = new Expenses(client);
+    this.clients = new Clients(client);
+    this.vendors = new Vendors(client);
+    this.products = new Products(client);
+    this.quotes = new Quotes(client);
+    this.webhooks = new Webhooks(client);
+    this.intelligence = new Intelligence(client);
+  }
+};
+var index_default = Frihet;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  APIError,
+  AuthenticationError,
+  Clients,
+  Expenses,
+  Frihet,
+  FrihetError,
+  Intelligence,
+  Invoices,
+  NotFoundError,
+  Products,
+  Quotes,
+  RateLimitError,
+  TimeoutError,
+  ValidationError,
+  Vendors,
+  Webhooks
+});
+//# sourceMappingURL=index.cjs.map