让开源，少一点语言距离。
npm包中文文档

@ekwo-ai/core

中文文档
0.25.2发布于 2026/11/13AGPL-3.0-onlyTypeScriptES Module构建来源已验证近 30 天下载 3209

TypeScript row types and a typed Supabase client for the Ekwo OS accounting schema.

原始使用文档
中文原文
文档目录4 节
  1. Install
  2. Usage
  3. API
  4. Licence

@ekwo-ai/core

TypeScript row types and a typed client for the Ekwo OS accounting schema.

  • Types of the whole schema, hand written so they stay readable: accounts, journals, entries and lines, documents and lines, taxes and tax postings, and the row shapes the report functions return.
  • The French FEC lives in @ekwo-ai/fec, which is MIT and depends on nothing. It is no longer re-exported here: import it from there.
  • A thin client over the functions that carry the accounting rules — post_document, reconcile, trial_balance, vat_return, fec_lines. Everything else is a table, and Supabase already exposes those as REST.
  • The functions the command line and the MCP server share — keeping the books, issuing an electronic invoice, proving a filing by its hash — so a rule exists once.
  • No runtime dependency of its own. @supabase/supabase-js is an optional peer; @ekwo-ai/fec is there because generateFec() on the client writes the file it has just fetched.

Install

npm install @ekwo-ai/core

Usage

import { EkwoClient } from '@ekwo-ai/core';
import { fecFileName } from '@ekwo-ai/fec';
import { createClient } from '@supabase/supabase-js';

const ekwo = new EkwoClient(createClient(url, key));

const entry = await ekwo.postDocument(documentId);
await ekwo.reconcile(receivableLineId, bankLineId);

const balance = await ekwo.trialBalance({ companyId, from: '2026-01-01', to: '2026-12-31' });
const boxes   = await ekwo.vatReturn({ companyId, from: '2026-07-01', to: '2026-09-30' });
const aged    = await ekwo.agedBalance(companyId, '2026-09-30', 'receivable');

const fec = await ekwo.generateFec({ companyId, from: '2026-01-01', to: '2026-12-31' });
await writeFile(fecFileName('123456789', '2026-12-31'), fec, 'utf8');

Without a Supabase client, format the file yourself from the rows of fec_lines():

import { checkFec, fromQueryRow, generateFec } from '@ekwo-ai/fec';

const lines = rows.map(fromQueryRow);
const violations = checkFec(lines);   // [] when the file is clean
const file = generateFec(lines, { decimalSeparator: ',', fieldSeparator: '|' });

API

ExportDescription
EkwoClientWrapper over the accounting functions of the schema.
initInstance, claimInstanceAdminRecord the installation and take the first administrator seat.
registerInstance, unregisterInstanceOpt into being reachable by Ekwo, and out again. Never required.
ACCOUNT_TYPES, internalGroup(type)The eighteen account types and their balance-sheet group.
isRegistered(instance)Whether the operator opted into registering with Ekwo.
isSale, isCreditNote, isAccountableDocument type predicates.
createContact, createDocument, addDocumentLine, updateDocumentLines, postDocument, recordPayment, reconcile, settleFromStatement, listDocuments, getDocument, …Keeping the books, once for every surface: the functions the MCP server and the ekwo command line both call. Each takes a Backend — five operations, select insert update remove rpc — that the caller implements over whatever reaches the database as a user. No accounting rule is in them; the schema holds those.
validateEinvoice, issueEinvoice, einvoiceStatus, listEinvoiceTransmissions, EinvoiceTransport, directoryTransportThe electronic invoice of a posted sale, through the einvoicing module, and the contract a transport implements — send, status, receive, lookup, with no credential crossing it. The one transport that ships writes files to a folder.
proveFile, upgradeFilingProofs, lookupFilingProof, checkProofThe sha256 of a filed file committed to Bitcoin through the public OpenTimestamps calendars, and checked later by anybody holding the file (docs/filing-proofs.md).
BooksError, isRefusalState, socleCode, isServiceRoleKeyWhat an error of that layer looks like, what counts as the database refusing, and the one key no surface accepts.
TypesInstance, InstanceAdmin, MemberRole, CompanyRole, Account, Journal, Entry, EntryLine, EkwoDocument, DocumentLine, Tax, TaxPosting, Contact, TrialBalanceRow, AgedBalanceRow, VatReturnRow, …

Amounts come back from Postgres as strings, and the types say so: numeric is carried as Decimal = string rather than rounded into a float on the way in.

Licence

AGPL-3.0-only © Ekwo AI.

版本与发布记录

@ekwo-ai/core 共发布 31 个版本，首次发布于 2026/09/19；过去 12 个月发布了 31 个版本。最新版本附带 npm provenance 构建来源证明，可追溯到公开的 CI 构建记录。

版本发布日期距今
0.25.2latest2026/11/13今天
0.25.02026/11/076 天前
0.24.12026/11/059 天前
0.24.02026/10/2816 天前
0.23.02026/10/2816 天前
0.22.02026/10/2816 天前

关于 @ekwo-ai/core 的常见问题

@ekwo-ai/core 是什么？

TypeScript row types and a typed Supabase client for the Ekwo OS accounting schema.

如何安装 @ekwo-ai/core？

在项目目录运行 npm install @ekwo-ai/core，或使用 pnpm add / yarn add / bun add。

@ekwo-ai/core 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@ekwo-ai/core 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module，更早的版本需要改用动态 import()。

@ekwo-ai/core 需要什么版本的 Node.js？

package.json 的 engines 字段要求 Node.js >=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

@ekwo-ai/core 可以商用吗？

@ekwo-ai/core 使用 AGPL-3.0-only 许可。最严格的 Copyleft：除分发外，通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括，不构成法律意见，请以许可原文为准。

@ekwo-ai/core 的下载量有多少？

根据 npm 官方下载统计，@ekwo-ai/core 在 2026/10/13 – 2026/11/11 这 30 天内被下载 3,209 次，日均约 107 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@ekwo-ai/core 还在维护吗？

最新版本 0.25.2 发布于 2026/11/13（今天）；至今共发布 31 个版本，其中过去 12 个月发布了 31 个；首次发布于 2026/09/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。