@databolsa/credit-sdk 3.7.0

package/README.md

@@ -0,0 +1,71 @@
+# @databolsa/credit-sdk
+
+[![npm version](https://img.shields.io/npm/v/@databolsa/credit-sdk?color=cb3837&logo=npm)](https://www.npmjs.com/package/@databolsa/credit-sdk)
+[![license](https://img.shields.io/npm/l/@databolsa/credit-sdk?color=2ea44f)](https://github.com/databolsahq/databolsa/blob/main/LICENSE)
+
+SDK TypeScript tipado para a API da **mesa de crédito do DataBolsa** — a camada de
+trabalho de quem acompanha crédito privado: watchlists de classes de FIDC, grade de
+acompanhamento, notas, alertas e limiares extraídos do regulamento. O contrato da mesa é
+**separado** do contrato de dados de mercado; este pacote é uma casca fina sobre ele e não
+calcula nada no cliente.
+
+## Uso rápido
+
+```bash
+npm install @databolsa/credit-sdk
+```
+
+```ts
+import { DataBolsaCredit, DataBolsaCreditError } from "@databolsa/credit-sdk";
+
+const desk = new DataBolsaCredit({ apiKey: process.env.DATABOLSA_CREDIT_API_KEY });
+
+const me = await desk.getMe();
+const org = me.organizations[0].org_slug;
+
+const { data: listas } = await desk.listWatchlists(org);
+const quadro = await desk.getWatchlistBoard(org, listas[0].slug);
+const { data: limiares } = await desk.listOrgRegulationTerms(org, { status: "pending" });
+
+try {
+  await desk.createNote(org, {
+    entity_id: quadro.rows[0].cnpj,
+    entity_kind: "fidc_class",
+    body: "revisar subordinação",
+  });
+} catch (err) {
+  if (err instanceof DataBolsaCreditError && err.problem?.code === "license_required") {
+    console.warn("licença vencida — escritas bloqueadas, leituras seguem abertas");
+  } else {
+    throw err;
+  }
+}
+```
+
+Toda operação, exceto as de conta, recebe o identificador da mesa (`slug` ou `id`) como
+primeiro argumento; `getMe()` lista em quais mesas a credencial pode agir. Opções do
+construtor: `baseUrl` (default `https://api.databolsa.com`), `apiKey` (chave pessoal
+`db_live_…`), `workspace` (id da mesa, vai no header
+`x-databolsa-workspace`), `credentials` e um `fetch` próprio. Mantenha a chave no servidor:
+ela abre a mesa inteira.
+
+## Comportamento que vale em toda rota
+
+- **Escopo é a mesa.** Recurso fora dela responde **404**, nunca 403 — não conclua que um
+  registro existe a partir do erro.
+- **Licença trava escrita, não leitura.** Licença vencida responde **402** com
+  `code: license_required` nas escritas; as leituras continuam.
+- **Unidade preservada.** Razões (inadimplência, alavancagem) viajam como fração
+  (`0.0445` = 4,45%); participação de cedente viaja como percentual (`90` = 90%). Ausência
+  de dado é `null`, nunca zero.
+- Erros seguem RFC 9457: `DataBolsaCreditError` carrega o `status` HTTP e o corpo
+  `problem+json` em `problem` (`title`, `detail`, `code`). Toda escrita é auditada.
+
+Os tipos de request e response são resolvidos por lookup no schema gerado do contrato com
+`openapi-typescript`; o pacote também exporta os paths crus como `CreditPaths`. O mesmo
+contrato está disponível como servidor MCP em `@databolsa/credit-mcp`, e os dados de
+mercado (ações, FIIs, fundos, crédito, macro) em `@databolsa/sdk`.
+
+## Licença
+
+Apache-2.0. O DataBolsa é infraestrutura de dados, não recomendação de investimento.

package/dist/client.d.ts

@@ -0,0 +1,408 @@
+/**
+ * Cliente fino da API da mesa de crédito do DataBolsa — cada método é uma operação do
+ * contrato, com request/response tipados por lookup no schema gerado (openapi-typescript).
+ * Autentica com a chave pessoal do membro (`db_live_...`); no portal da mesa, cookies de
+ * sessão via `credentials: "include"`.
+ *
+ * A API age numa mesa da pessoa: a indicada em `workspace` (id da organização) ou, sem
+ * ela, a primeira em que a mesa está habilitada.
+ */
+import type { paths } from "./schema";
+type JsonOf<T> = T extends {
+    content: {
+        "application/json": infer J;
+    };
+} ? J : never;
+type Body<P extends keyof paths, M extends keyof paths[P]> = paths[P][M] extends {
+    requestBody?: infer B;
+} ? JsonOf<NonNullable<B>> : never;
+export declare class DataBolsaCreditError extends Error {
+    readonly status: number;
+    readonly problem: {
+        title?: string;
+        detail?: string;
+        code?: string;
+    } | null;
+    constructor(status: number, problem: {
+        title?: string;
+        detail?: string;
+        code?: string;
+    } | null);
+}
+export interface CreditClientOptions {
+    /** Origem da API (default: https://api.databolsa.com). Os paths já têm /v1/desk. */
+    baseUrl?: string;
+    /** Chave pessoal `db_live_...`. Omitida no portal (sessão via cookie). */
+    apiKey?: string;
+    /** Id da organização em que agir (header `x-databolsa-workspace`). */
+    workspace?: string;
+    /** `include` no portal (cookie de sessão same-origin). */
+    credentials?: "omit" | "same-origin" | "include";
+    fetch?: typeof fetch;
+}
+export declare class DataBolsaCredit {
+    private readonly baseUrl;
+    private readonly apiKey?;
+    private readonly workspace?;
+    private readonly credentials?;
+    private readonly fetchImpl;
+    constructor(opts?: CreditClientOptions);
+    private request;
+    getMe(): Promise<{
+        user_id: string | null;
+        email: string | null;
+        name: string | null;
+        organizations: {
+            org_id: string;
+            org_slug: string;
+            org_name: string;
+            role: "owner" | "admin" | "analyst" | "viewer";
+            member_id: string;
+        }[];
+    }>;
+    acceptInvitation(body: Body<"/v1/desk/invitations/accept", "post">): Promise<{
+        org_id: string;
+        org_slug: string;
+        member_id: string;
+        role: string;
+    }>;
+    getOrganization(org: string): Promise<{
+        id: string;
+        slug: string;
+        name: string;
+        cnpj: string | null;
+        cvm_registration: string | null;
+        status: string;
+    }>;
+    updateOrganization(org: string, body: Body<"/v1/desk/orgs/{org}", "patch">): Promise<{
+        id: string;
+        slug: string;
+        name: string;
+        cnpj: string | null;
+        cvm_registration: string | null;
+        status: string;
+    }>;
+    getLicense(org: string): Promise<{
+        plan: string | null;
+        seats_limit: number;
+        watched_limit: number | null;
+        expires_at: string | null;
+        expired: boolean;
+    }>;
+    listMembers(org: string): Promise<{
+        data: {
+            id: string;
+            role: string;
+            display_name: string | null;
+            status: string;
+            created_at: string;
+        }[];
+    }>;
+    assignSeat(org: string, body: Body<"/v1/desk/orgs/{org}/members", "post">): Promise<{
+        id: string;
+        role: string;
+        display_name: string | null;
+        status: string;
+        created_at: string;
+    }>;
+    updateMember(org: string, memberId: string, body: Body<"/v1/desk/orgs/{org}/members/{memberId}", "patch">): Promise<{
+        id: string;
+        role: string;
+        display_name: string | null;
+        status: string;
+        created_at: string;
+    }>;
+    listInvitations(org: string): Promise<{
+        data: {
+            id: string;
+            email: string;
+            role: string;
+            status: string;
+            expires_at: string;
+        }[];
+    }>;
+    createInvitation(org: string, body: Body<"/v1/desk/orgs/{org}/invitations", "post">): Promise<{
+        invitation_id: string;
+        invite_url: string;
+    }>;
+    revokeInvitation(org: string, invitationId: string): Promise<{
+        revoked: boolean;
+    }>;
+    listAudit(org: string, params?: {
+        entityId?: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        data: {
+            id: string;
+            action: string;
+            summary: string | null;
+            via: string;
+            actor_member_id: string | null;
+            actor_display_name: string | null;
+            entity_type: string | null;
+            entity_id: string | null;
+            created_at: string;
+        }[];
+        meta: {
+            next_cursor: string | null;
+            count: number;
+        };
+    }>;
+    listWatchlists(org: string): Promise<{
+        data: {
+            id: string;
+            slug: string;
+            name: string;
+            description: string | null;
+            kind: string;
+            item_count: number;
+        }[];
+    }>;
+    createWatchlist(org: string, body: Body<"/v1/desk/orgs/{org}/watchlists", "post">): Promise<{
+        id: string;
+        slug: string;
+        name: string;
+        description: string | null;
+        kind: string;
+        item_count: number;
+    }>;
+    deleteWatchlist(org: string, list: string): Promise<{
+        deleted: boolean;
+    }>;
+    listWatchlistItems(org: string, list: string): Promise<{
+        data: {
+            cnpj: string;
+            entity_kind: string;
+            label: string | null;
+            relation: string;
+            position: number;
+        }[];
+    }>;
+    addWatchlistItems(org: string, list: string, body: Body<"/v1/desk/orgs/{org}/watchlists/{list}/items", "post">): Promise<{
+        added: number;
+        skipped: number;
+    }>;
+    removeWatchlistItem(org: string, list: string, cnpj: string): Promise<{
+        removed: boolean;
+    }>;
+    getWatchlistBoard(org: string, list: string): Promise<{
+        watchlist: {
+            id: string;
+            slug: string;
+            name: string;
+            kind: string;
+        };
+        latest_competence: string | null;
+        columns: {
+            metric: string;
+            label: string;
+            unit: string;
+            help: string;
+        }[];
+        rows: {
+            cnpj: string;
+            entity_kind: string;
+            relation: string;
+            label: string | null;
+            name: string | null;
+            reference_date: string | null;
+            unknown: boolean;
+            cells: {
+                metric: string;
+                value: number | null;
+                unit: string;
+            }[];
+        }[];
+    }>;
+    getGrid(org: string): Promise<{
+        columns: {
+            metric: string;
+            position: number;
+        }[];
+        catalog: {
+            metric: string;
+            label: string;
+            unit: string;
+            help: string;
+        }[];
+    }>;
+    setGrid(org: string, body: Body<"/v1/desk/orgs/{org}/grid", "put">): Promise<{
+        columns: string[];
+    }>;
+    listAlerts(org: string, list: string): Promise<{
+        data: {
+            key: string;
+            cnpj: string;
+            name: string | null;
+            source: "covenant" | "rule" | "reporting";
+            severity: "info" | "attention" | "critical";
+            metric: string;
+            value: number | null;
+            threshold: number | null;
+            distance: number | null;
+            reference_date: string | null;
+            title: string;
+            evidence: {
+                doc_id: string | null;
+                page: number | null;
+                quote: string | null;
+            } | null;
+            status: "open" | "acknowledged" | "muted";
+            first_detected_at?: string | null;
+        }[];
+        meta: {
+            count: number;
+        };
+    }>;
+    listAlertHistory(org: string, params?: {
+        cnpj?: string;
+        source?: "covenant" | "rule" | "reporting";
+        since?: string;
+        limit?: number;
+    }): Promise<{
+        data: {
+            alert_key: string;
+            cnpj: string;
+            source: string;
+            severity: string;
+            metric: string;
+            value: number | null;
+            threshold: number | null;
+            distance: number | null;
+            reference_date: string | null;
+            title: string;
+            detected_at: string;
+        }[];
+        meta: {
+            count: number;
+        };
+    }>;
+    acknowledgeAlert(org: string, key: string, body: Body<"/v1/desk/orgs/{org}/alerts/{key}/ack", "post">): Promise<{
+        key: string;
+        status: string;
+    }>;
+    listAlertRules(org: string): Promise<{
+        data: {
+            id: string;
+            metric: string;
+            comparator: string;
+            threshold: number;
+            severity: string;
+            enabled: boolean;
+        }[];
+    }>;
+    upsertAlertRule(org: string, body: Body<"/v1/desk/orgs/{org}/alert-rules", "put">): Promise<{
+        id: string;
+        metric: string;
+        comparator: string;
+        threshold: number;
+        severity: string;
+        enabled: boolean;
+    }>;
+    deleteAlertRule(org: string, ruleId: string): Promise<{
+        deleted: boolean;
+    }>;
+    listNotes(org: string, params?: {
+        entityId?: string;
+        limit?: number;
+    }): Promise<{
+        data: {
+            id: string;
+            entity_kind: string;
+            entity_id: string;
+            body: string;
+            author_member_id: string | null;
+            author_name: string | null;
+            created_at: string;
+            updated_at: string;
+        }[];
+    }>;
+    createNote(org: string, body: Body<"/v1/desk/orgs/{org}/notes", "post">): Promise<{
+        id: string;
+    }>;
+    deleteNote(org: string, noteId: string): Promise<{
+        deleted: boolean;
+    }>;
+    listRegulationTerms(org: string, cnpj: string, params?: {
+        includeHistory?: boolean;
+        status?: "pending" | "confirmed" | "rejected";
+    }): Promise<{
+        data: {
+            id: string;
+            cnpj: string;
+            term: string;
+            label: string;
+            value_num: number | null;
+            value_text: string | null;
+            unit: string | null;
+            doc_id: string | null;
+            doc_page: number | null;
+            quote: string | null;
+            confidence: number | null;
+            status: "pending" | "confirmed" | "rejected";
+            valid_from: string;
+            valid_to: string | null;
+        }[];
+        meta: {
+            terms: string[];
+        };
+    }>;
+    proposeRegulationTerm(org: string, cnpj: string, body: Body<"/v1/desk/orgs/{org}/classes/{cnpj}/terms", "post">): Promise<{
+        id: string;
+        cnpj: string;
+        term: string;
+        label: string;
+        value_num: number | null;
+        value_text: string | null;
+        unit: string | null;
+        doc_id: string | null;
+        doc_page: number | null;
+        quote: string | null;
+        confidence: number | null;
+        status: "pending" | "confirmed" | "rejected";
+        valid_from: string;
+        valid_to: string | null;
+    }>;
+    listOrgRegulationTerms(org: string, params?: {
+        status?: "pending" | "confirmed" | "rejected";
+        limit?: number;
+    }): Promise<{
+        data: {
+            id: string;
+            cnpj: string;
+            term: string;
+            label: string;
+            value_num: number | null;
+            value_text: string | null;
+            unit: string | null;
+            doc_id: string | null;
+            doc_page: number | null;
+            quote: string | null;
+            confidence: number | null;
+            status: "pending" | "confirmed" | "rejected";
+            valid_from: string;
+            valid_to: string | null;
+        }[];
+        meta: {
+            count: number;
+        };
+    }>;
+    reviewRegulationTerm(org: string, termId: string, body: Body<"/v1/desk/orgs/{org}/terms/{termId}/review", "post">): Promise<{
+        id: string;
+        cnpj: string;
+        term: string;
+        label: string;
+        value_num: number | null;
+        value_text: string | null;
+        unit: string | null;
+        doc_id: string | null;
+        doc_page: number | null;
+        quote: string | null;
+        confidence: number | null;
+        status: "pending" | "confirmed" | "rejected";
+        valid_from: string;
+        valid_to: string | null;
+    }>;
+}
+export {};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { DataBolsaCredit, DataBolsaCreditError, type CreditClientOptions } from "./client";
+export type { paths as CreditPaths } from "./schema";

package/dist/index.js

@@ -0,0 +1,161 @@
+// src/client.ts
+class DataBolsaCreditError extends Error {
+  status;
+  problem;
+  constructor(status, problem) {
+    super(problem?.detail ?? problem?.title ?? `HTTP ${status}`);
+    this.status = status;
+    this.problem = problem;
+  }
+}
+
+class DataBolsaCredit {
+  baseUrl;
+  apiKey;
+  workspace;
+  credentials;
+  fetchImpl;
+  constructor(opts = {}) {
+    this.baseUrl = (opts.baseUrl ?? "https://api.databolsa.com").replace(/\/+$/, "");
+    this.apiKey = opts.apiKey;
+    this.workspace = opts.workspace;
+    this.credentials = opts.credentials;
+    this.fetchImpl = opts.fetch ?? fetch;
+  }
+  async request(method, path, body, query) {
+    const url = new URL(`${this.baseUrl}${path}`);
+    for (const [k, v] of Object.entries(query ?? {}))
+      if (v != null)
+        url.searchParams.set(k, String(v));
+    const res = await this.fetchImpl(url, {
+      method,
+      credentials: this.credentials,
+      headers: {
+        ...body !== undefined ? { "content-type": "application/json" } : {},
+        ...this.apiKey ? { authorization: `Bearer ${this.apiKey}` } : {},
+        ...this.workspace ? { "x-databolsa-workspace": this.workspace } : {}
+      },
+      body: body === undefined ? undefined : JSON.stringify(body)
+    });
+    if (!res.ok) {
+      const problem = await res.json().catch(() => null);
+      throw new DataBolsaCreditError(res.status, problem);
+    }
+    return await res.json();
+  }
+  getMe() {
+    return this.request("GET", "/v1/desk/me");
+  }
+  acceptInvitation(body) {
+    return this.request("POST", "/v1/desk/invitations/accept", body);
+  }
+  getOrganization(org) {
+    return this.request("GET", `/v1/desk/orgs/${enc(org)}`);
+  }
+  updateOrganization(org, body) {
+    return this.request("PATCH", `/v1/desk/orgs/${enc(org)}`, body);
+  }
+  getLicense(org) {
+    return this.request("GET", `/v1/desk/orgs/${enc(org)}/license`);
+  }
+  listMembers(org) {
+    return this.request("GET", `/v1/desk/orgs/${enc(org)}/members`);
+  }
+  assignSeat(org, body) {
+    return this.request("POST", `/v1/desk/orgs/${enc(org)}/members`, body);
+  }
+  updateMember(org, memberId, body) {
+    return this.request("PATCH", `/v1/desk/orgs/${enc(org)}/members/${enc(memberId)}`, body);
+  }
+  listInvitations(org) {
+    return this.request("GET", `/v1/desk/orgs/${enc(org)}/invitations`);
+  }
+  createInvitation(org, body) {
+    return this.request("POST", `/v1/desk/orgs/${enc(org)}/invitations`, body);
+  }
+  revokeInvitation(org, invitationId) {
+    return this.request("DELETE", `/v1/desk/orgs/${enc(org)}/invitations/${enc(invitationId)}`);
+  }
+  listAudit(org, params) {
+    return this.request("GET", `/v1/desk/orgs/${enc(org)}/audit`, undefined, { entity_id: params?.entityId, cursor: params?.cursor, limit: params?.limit });
+  }
+  listWatchlists(org) {
+    return this.request("GET", `/v1/desk/orgs/${enc(org)}/watchlists`);
+  }
+  createWatchlist(org, body) {
+    return this.request("POST", `/v1/desk/orgs/${enc(org)}/watchlists`, body);
+  }
+  deleteWatchlist(org, list) {
+    return this.request("DELETE", `/v1/desk/orgs/${enc(org)}/watchlists/${enc(list)}`);
+  }
+  listWatchlistItems(org, list) {
+    return this.request("GET", `/v1/desk/orgs/${enc(org)}/watchlists/${enc(list)}/items`);
+  }
+  addWatchlistItems(org, list, body) {
+    return this.request("POST", `/v1/desk/orgs/${enc(org)}/watchlists/${enc(list)}/items`, body);
+  }
+  removeWatchlistItem(org, list, cnpj) {
+    return this.request("DELETE", `/v1/desk/orgs/${enc(org)}/watchlists/${enc(list)}/items/${enc(cnpj)}`);
+  }
+  getWatchlistBoard(org, list) {
+    return this.request("GET", `/v1/desk/orgs/${enc(org)}/watchlists/${enc(list)}/board`);
+  }
+  getGrid(org) {
+    return this.request("GET", `/v1/desk/orgs/${enc(org)}/grid`);
+  }
+  setGrid(org, body) {
+    return this.request("PUT", `/v1/desk/orgs/${enc(org)}/grid`, body);
+  }
+  listAlerts(org, list) {
+    return this.request("GET", `/v1/desk/orgs/${enc(org)}/watchlists/${enc(list)}/alerts`);
+  }
+  listAlertHistory(org, params) {
+    return this.request("GET", `/v1/desk/orgs/${enc(org)}/alert-history`, undefined, { cnpj: params?.cnpj, source: params?.source, since: params?.since, limit: params?.limit });
+  }
+  acknowledgeAlert(org, key, body) {
+    return this.request("POST", `/v1/desk/orgs/${enc(org)}/alerts/${enc(key)}/ack`, body);
+  }
+  listAlertRules(org) {
+    return this.request("GET", `/v1/desk/orgs/${enc(org)}/alert-rules`);
+  }
+  upsertAlertRule(org, body) {
+    return this.request("PUT", `/v1/desk/orgs/${enc(org)}/alert-rules`, body);
+  }
+  deleteAlertRule(org, ruleId) {
+    return this.request("DELETE", `/v1/desk/orgs/${enc(org)}/alert-rules/${enc(ruleId)}`);
+  }
+  listNotes(org, params) {
+    return this.request("GET", `/v1/desk/orgs/${enc(org)}/notes`, undefined, {
+      entity_id: params?.entityId,
+      limit: params?.limit
+    });
+  }
+  createNote(org, body) {
+    return this.request("POST", `/v1/desk/orgs/${enc(org)}/notes`, body);
+  }
+  deleteNote(org, noteId) {
+    return this.request("DELETE", `/v1/desk/orgs/${enc(org)}/notes/${enc(noteId)}`);
+  }
+  listRegulationTerms(org, cnpj, params) {
+    return this.request("GET", `/v1/desk/orgs/${enc(org)}/classes/${enc(cnpj)}/terms`, undefined, { include_history: params?.includeHistory, status: params?.status });
+  }
+  proposeRegulationTerm(org, cnpj, body) {
+    return this.request("POST", `/v1/desk/orgs/${enc(org)}/classes/${enc(cnpj)}/terms`, body);
+  }
+  listOrgRegulationTerms(org, params) {
+    return this.request("GET", `/v1/desk/orgs/${enc(org)}/terms`, undefined, {
+      status: params?.status,
+      limit: params?.limit
+    });
+  }
+  reviewRegulationTerm(org, termId, body) {
+    return this.request("POST", `/v1/desk/orgs/${enc(org)}/terms/${enc(termId)}/review`, body);
+  }
+}
+function enc(segment) {
+  return encodeURIComponent(segment);
+}
+export {
+  DataBolsaCreditError,
+  DataBolsaCredit
+};