financy 0.3.0 → 0.4.1

package/dist/{chunk-VE5WZRGU.js → chunk-FKAHEAV6.js}

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "financy",
-  version: "0.3.0",
+  version: "0.4.1",
   description: "Your Open-Finance accounts, balances and transactions in the terminal \u2014 with an embedded MCP server and agent skills",
   type: "module",
   bin: {
@@ -109,7 +109,7 @@ var authFailed = (message = "authentication failed \u2014 check your credentials
 var planNotEligible = () => new CliError(
   EXIT.PLAN,
   "NOT_AVAILABLE_ON_PLAN",
-  "the API is available on Starter and Pro plans \u2014 upgrade in Financy \u2192 Settings \u2192 Plan"
+  "the API is available on every paid plan, including Starter, Pro, and Ultra \u2014 upgrade in Financy \u2192 Settings \u2192 Plan"
 );
 var forbidden = (detail) => new CliError(EXIT.PLAN, "FORBIDDEN", `the API denied this request (403): ${detail}`);
 var insufficientCredits = (cost, balance) => new CliError(
@@ -120,6 +120,29 @@ var insufficientCredits = (cost, balance) => new CliError(
 );
 var noRefreshableConnections = (message = "no connections are eligible for refresh") => new CliError(EXIT.UNEXPECTED, "NO_REFRESHABLE_CONNECTIONS", message);
 var apiUnavailable = (message = "the Open-Finance API is unavailable \u2014 check your connection and try again") => new CliError(EXIT.API, "API_UNAVAILABLE", message);
+var PLAN_TYPES = /* @__PURE__ */ new Set([
+  "UPGRADE_REQUIRED",
+  "INTEGRATION_LIMIT_REACHED",
+  "NOT_ENTITLED",
+  "ENTITLEMENT_NOT_PROVISIONED"
+]);
+function integrationsExitCode(type, status) {
+  if (type === "SIGN_IN_AGAIN") return EXIT.AUTH;
+  if (PLAN_TYPES.has(type) || status === 403) return EXIT.PLAN;
+  if (status === 404) return EXIT.NOT_FOUND;
+  if (status === 400 || status === 422) return EXIT.USAGE;
+  if (status === 429 || status >= 500) return EXIT.API;
+  return EXIT.UNEXPECTED;
+}
+function integrationsError(body, status) {
+  const hint = body.action?.url ? ` \u2014 ${body.action.url}` : body.type === "UPGRADE_REQUIRED" ? " \u2014 upgrade in Financy \u2192 Settings \u2192 Plan" : "";
+  return new CliError(integrationsExitCode(body.type, status), body.type, `${body.message}${hint}`, {
+    retryable: body.retryable === true,
+    userActionRequired: body.userActionRequired === true,
+    ...body.action ? { action: body.action } : {},
+    ...body.requestId ? { requestId: body.requestId } : {}
+  });
+}
 
 // src/config.ts
 import { homedir } from "os";
@@ -141,6 +164,16 @@ function sanitizeCredential(raw) {
 var DEFAULT_AUTH_TOKEN_URL = "https://api.open-finance.ai/oauth/token";
 var DEFAULT_API_BASE_URL = "https://api.open-finance.ai/v2";
 var DEFAULT_CHAT_BASE_URL = "https://api.open-finance.ai/chat/chat";
+var DEFAULT_INTEGRATIONS_BASE_URL = "https://api.open-finance.ai/integrations";
+function resolveIntegrationsBaseUrl(env) {
+  if (env.FINANCY_INTEGRATIONS_URL) return env.FINANCY_INTEGRATIONS_URL;
+  if (!env.FINANCY_API_URL) return DEFAULT_INTEGRATIONS_BASE_URL;
+  try {
+    return `${new URL(env.FINANCY_API_URL).origin}/integrations`;
+  } catch {
+    return DEFAULT_INTEGRATIONS_BASE_URL;
+  }
+}
 function resolveConfigDir(env) {
   if (env.FINANCY_CONFIG_DIR) return env.FINANCY_CONFIG_DIR;
   const base = env.XDG_CONFIG_HOME || join(homedir(), ".config");
@@ -151,6 +184,7 @@ function resolveEndpoints(env) {
     authTokenUrl: env.FINANCY_AUTH_URL ?? DEFAULT_AUTH_TOKEN_URL,
     apiBaseUrl: env.FINANCY_API_URL ?? DEFAULT_API_BASE_URL,
     chatBaseUrl: env.FINANCY_CHAT_URL ?? DEFAULT_CHAT_BASE_URL,
+    integrationsBaseUrl: resolveIntegrationsBaseUrl(env),
     configDir: resolveConfigDir(env)
   };
 }
@@ -320,13 +354,14 @@ async function getAccessToken(config, now) {
   }
   return mintAndCache(config);
 }
-async function authorized(config, now, request) {
+var isAuthFailure = (error) => error.code === "AUTH_FAILED";
+async function authorized(config, now, request, remintOn = isAuthFailure) {
   if (config.bearerToken) return request(config.bearerToken);
   const token = await getAccessToken(config, now);
   try {
     return await request(token);
   } catch (error) {
-    if (error instanceof CliError && error.code === "AUTH_FAILED") {
+    if (error instanceof CliError && remintOn(error)) {
       return await request(await mintAndCache(config));
     }
     throw error;
@@ -410,6 +445,195 @@ async function getConnections(config, token) {
   return getPage(config, token, "/connections");
 }
 
+// src/integrations-api.ts
+function isApiError(value) {
+  return value !== null && typeof value === "object" && typeof value.type === "string" && typeof value.message === "string";
+}
+function integrationsUrl(config, path, query) {
+  const url = new URL(config.integrationsBaseUrl.replace(/\/+$/, "") + path);
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== void 0) url.searchParams.set(key, value);
+  }
+  return url.toString();
+}
+async function send(config, token, method, path, options = {}) {
+  const res = await httpFetch(integrationsUrl(config, path, options.query ?? {}), {
+    method,
+    headers: {
+      authorization: `Bearer ${token}`,
+      accept: "application/json",
+      "user-agent": USER_AGENT,
+      ...options.body === void 0 ? {} : { "content-type": "application/json" },
+      ...options.headers
+    },
+    ...options.body === void 0 ? {} : { body: JSON.stringify(options.body) },
+    signal: config.abortSignal
+  });
+  const parsed = await res.json().catch(() => void 0);
+  if (res.ok) {
+    debugBody(path, parsed);
+    return { body: parsed ?? {}, replayed: res.headers.get("idempotent-replayed") === "true" };
+  }
+  if (isApiError(parsed)) throw integrationsError(parsed, res.status);
+  if (res.status === 401) throw authFailed();
+  throw apiUnavailable(`the integrations API returned HTTP ${res.status}`);
+}
+async function integrationsGet(config, token, path, query = {}) {
+  return (await send(config, token, "GET", path, { query })).body;
+}
+async function integrationsPost(config, token, path, body, headers = {}) {
+  return send(config, token, "POST", path, { body, headers });
+}
+
+// src/core/integrations.ts
+var PATH_SEGMENT = /^[A-Za-z0-9_-]{1,128}$/;
+function segment(name, value) {
+  if (!PATH_SEGMENT.test(value)) {
+    throw new CliError(EXIT.USAGE, "INVALID_ARGUMENT", `'${value}' is not a valid ${name}`);
+  }
+  return value;
+}
+var isScopeError = (error) => error.code === "INSUFFICIENT_SCOPE";
+async function integrationsAuthorized(config, now, request) {
+  try {
+    return await authorized(config, now, request, (e) => e.code === "AUTH_FAILED" || isScopeError(e));
+  } catch (error) {
+    if (error instanceof CliError && isScopeError(error)) {
+      throw new CliError(
+        EXIT.PLAN,
+        "INSUFFICIENT_SCOPE",
+        `this API key doesn't have integration access \u2014 if the key is set to read-only, turn off "\u05DE\u05D9\u05D3\u05E2 \u05D1\u05DC\u05D1\u05D3" (information only) in Financy \u2192 Settings \u2192 API access; otherwise integrations need a Starter plan or above, and the key may need refreshing: rotate it there, then run financy setup`,
+        error.extra
+      );
+    }
+    throw error;
+  }
+}
+var get = (config, now, path, query = {}) => integrationsAuthorized(config, now, (token) => integrationsGet(config, token, path, query));
+async function cursorList(config, now, path, query, all) {
+  const data = [];
+  let cursor = query.cursor;
+  let freshness;
+  do {
+    const page = await get(config, now, path, { ...query, cursor });
+    data.push(...Array.isArray(page.items) ? page.items : []);
+    freshness = page.freshness;
+    cursor = page.nextCursor ?? void 0;
+  } while (all && cursor);
+  return {
+    data,
+    count: data.length,
+    nextPage: all ? null : cursor ?? null,
+    ...freshness === void 0 ? {} : { freshness }
+  };
+}
+function fetchIntegrations(config, now) {
+  return cursorList(config, now, "/", {}, false);
+}
+async function fetchIntegration(config, now, id) {
+  const body = await get(config, now, `/${segment("integration id", id)}`);
+  return { data: body.integration };
+}
+async function fetchReceivables(config, now, args) {
+  const ids = (args.integrations ?? []).flatMap((v) => v.split(",")).filter((v) => v.length > 0);
+  const body = await get(config, now, "/receivables", {
+    integrationIds: ids.length > 0 ? ids.map((id) => segment("integration id", id)).join(",") : void 0,
+    asOf: args.asOf,
+    format: args.detailed ? "detailed" : void 0,
+    customerLimit: args.customerLimit,
+    includeProforma: args.includeProforma === void 0 ? void 0 : String(args.includeProforma)
+  });
+  return { data: body };
+}
+function fetchInvoicingDocuments(config, now, integrationId, args) {
+  return cursorList(
+    config,
+    now,
+    `/${segment("integration id", integrationId)}/documents`,
+    {
+      status: args.status,
+      type: args.type,
+      counterpartyId: args.customer,
+      issuedFrom: args.from,
+      issuedTo: args.to,
+      receivableOnly: args.receivableOnly ? "true" : void 0,
+      number: args.number,
+      limit: args.limit,
+      cursor: args.cursor
+    },
+    !!args.all
+  );
+}
+async function fetchInvoicingDocument(config, now, integrationId, documentId) {
+  const body = await get(
+    config,
+    now,
+    `/${segment("integration id", integrationId)}/documents/${segment("document id", documentId)}`
+  );
+  return { data: body.document, ...body.freshness === void 0 ? {} : { freshness: body.freshness } };
+}
+function fetchInvoicingCustomers(config, now, integrationId, args) {
+  return cursorList(
+    config,
+    now,
+    `/${segment("integration id", integrationId)}/customers`,
+    { q: args.search, limit: args.limit, cursor: args.cursor },
+    !!args.all
+  );
+}
+async function fetchInvoicingCustomer(config, now, integrationId, customerId) {
+  const body = await get(
+    config,
+    now,
+    `/${segment("integration id", integrationId)}/customers/${segment("customer id", customerId)}`
+  );
+  return { data: body.customer, ...body.freshness === void 0 ? {} : { freshness: body.freshness } };
+}
+function fetchProposals(config, now, args) {
+  return cursorList(
+    config,
+    now,
+    "/proposals",
+    {
+      integrationId: args.integration === void 0 ? void 0 : segment("integration id", args.integration),
+      status: args.status,
+      clientReference: args.reference,
+      limit: args.limit
+    },
+    false
+  );
+}
+async function fetchProposal(config, now, id) {
+  const body = await get(config, now, `/proposals/${segment("proposal id", id)}`);
+  return { data: body.proposal };
+}
+function assertDraftBody(body) {
+  const obj = body;
+  if (body === null || typeof body !== "object" || Array.isArray(body) || typeof obj.action !== "string" || !Array.isArray(obj.items)) {
+    throw new CliError(
+      EXIT.USAGE,
+      "INVALID_DRAFT",
+      'a draft is a JSON object with an "action" (e.g. "create_tax_invoice") and an "items" array'
+    );
+  }
+  return body;
+}
+async function createDraft(config, now, integrationId, body, idempotencyKey) {
+  const draft = assertDraftBody(body);
+  const path = `/${segment("integration id", integrationId)}/proposals`;
+  const headers = idempotencyKey ? { "idempotency-key": idempotencyKey } : {};
+  const res = await integrationsAuthorized(
+    config,
+    now,
+    (token) => integrationsPost(config, token, path, draft, headers)
+  );
+  return {
+    data: res.body.proposal,
+    replayed: res.replayed,
+    ...idempotencyKey ? { idempotencyKey } : {}
+  };
+}
+
 // src/core/status.ts
 var STALE_THRESHOLD_DAYS = 2;
 function toRow(c) {
@@ -569,5 +793,15 @@ export {
   fetchTransaction,
   fetchCategories,
   fetchProviders,
-  fetchBranches
+  fetchBranches,
+  fetchIntegrations,
+  fetchIntegration,
+  fetchReceivables,
+  fetchInvoicingDocuments,
+  fetchInvoicingDocument,
+  fetchInvoicingCustomers,
+  fetchInvoicingCustomer,
+  fetchProposals,
+  fetchProposal,
+  createDraft
 };

package/dist/lib.d.ts

@@ -7,6 +7,7 @@ interface Endpoints {
     authTokenUrl: string;
     apiBaseUrl: string;
     chatBaseUrl: string;
+    integrationsBaseUrl: string;
     configDir: string;
 }
 type Config = Credentials & Endpoints & {

package/dist/lib.js

@@ -43,7 +43,7 @@ var authFailed = (message = "authentication failed \u2014 check your credentials
 var planNotEligible = () => new CliError(
   EXIT.PLAN,
   "NOT_AVAILABLE_ON_PLAN",
-  "the API is available on Starter and Pro plans \u2014 upgrade in Financy \u2192 Settings \u2192 Plan"
+  "the API is available on every paid plan, including Starter, Pro, and Ultra \u2014 upgrade in Financy \u2192 Settings \u2192 Plan"
 );
 var forbidden = (detail) => new CliError(EXIT.PLAN, "FORBIDDEN", `the API denied this request (403): ${detail}`);
 var insufficientCredits = (cost, balance) => new CliError(
@@ -59,6 +59,16 @@ var apiUnavailable = (message = "the Open-Finance API is unavailable \u2014 chec
 var DEFAULT_AUTH_TOKEN_URL = "https://api.open-finance.ai/oauth/token";
 var DEFAULT_API_BASE_URL = "https://api.open-finance.ai/v2";
 var DEFAULT_CHAT_BASE_URL = "https://api.open-finance.ai/chat/chat";
+var DEFAULT_INTEGRATIONS_BASE_URL = "https://api.open-finance.ai/integrations";
+function resolveIntegrationsBaseUrl(env) {
+  if (env.FINANCY_INTEGRATIONS_URL) return env.FINANCY_INTEGRATIONS_URL;
+  if (!env.FINANCY_API_URL) return DEFAULT_INTEGRATIONS_BASE_URL;
+  try {
+    return `${new URL(env.FINANCY_API_URL).origin}/integrations`;
+  } catch {
+    return DEFAULT_INTEGRATIONS_BASE_URL;
+  }
+}
 function resolveConfigDir(env) {
   if (env.FINANCY_CONFIG_DIR) return env.FINANCY_CONFIG_DIR;
   const base = env.XDG_CONFIG_HOME || join(homedir(), ".config");
@@ -69,6 +79,7 @@ function resolveEndpoints(env) {
     authTokenUrl: env.FINANCY_AUTH_URL ?? DEFAULT_AUTH_TOKEN_URL,
     apiBaseUrl: env.FINANCY_API_URL ?? DEFAULT_API_BASE_URL,
     chatBaseUrl: env.FINANCY_CHAT_URL ?? DEFAULT_CHAT_BASE_URL,
+    integrationsBaseUrl: resolveIntegrationsBaseUrl(env),
     configDir: resolveConfigDir(env)
   };
 }
@@ -155,7 +166,7 @@ function notConfigured(result) {
 // package.json
 var package_default = {
   name: "financy",
-  version: "0.3.0",
+  version: "0.4.1",
   description: "Your Open-Finance accounts, balances and transactions in the terminal \u2014 with an embedded MCP server and agent skills",
   type: "module",
   bin: {
@@ -320,13 +331,14 @@ async function getAccessToken(config, now) {
   }
   return mintAndCache(config);
 }
-async function authorized(config, now, request) {
+var isAuthFailure = (error) => error.code === "AUTH_FAILED";
+async function authorized(config, now, request, remintOn = isAuthFailure) {
   if (config.bearerToken) return request(config.bearerToken);
   const token = await getAccessToken(config, now);
   try {
     return await request(token);
   } catch (error) {
-    if (error instanceof CliError && error.code === "AUTH_FAILED") {
+    if (error instanceof CliError && remintOn(error)) {
       return await request(await mintAndCache(config));
     }
     throw error;
@@ -686,8 +698,11 @@ function errorEnvelope(error) {
   return { error: { code: e.code, message: e.message, ...e.extra } };
 }
 async function callTool(name, args, io) {
+  return dispatchTool(BY_NAME, name, args, io);
+}
+async function dispatchTool(byName, name, args, io) {
   try {
-    const tool = BY_NAME.get(name);
+    const tool = byName.get(name);
     if (!tool) {
       throw new CliError(EXIT.USAGE, "UNKNOWN_TOOL", `no tool named '${name}'`);
     }