@tofound/billing 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +46 -0
- package/LICENSE +3 -0
- package/README.md +34 -2
- package/dist/domain/errors.d.ts +14 -0
- package/dist/domain/errors.js +21 -0
- package/dist/domain/money.d.ts +21 -0
- package/dist/domain/money.js +77 -0
- package/dist/domain/types.d.ts +165 -0
- package/dist/domain/types.js +18 -0
- package/dist/drizzle/index.d.ts +3 -0
- package/dist/drizzle/index.js +3 -0
- package/dist/drizzle/schema-factory.d.ts +586 -0
- package/dist/drizzle/schema-factory.js +206 -0
- package/dist/drizzle/store.d.ts +20 -0
- package/dist/drizzle/store.js +124 -0
- package/dist/inbox/apply.d.ts +48 -0
- package/dist/inbox/apply.js +299 -0
- package/dist/inbox/conformance.d.ts +20 -0
- package/dist/inbox/conformance.js +254 -0
- package/dist/inbox/drizzle.d.ts +14 -0
- package/dist/inbox/drizzle.js +203 -0
- package/dist/inbox/ingest.d.ts +108 -0
- package/dist/inbox/ingest.js +404 -0
- package/dist/inbox/memory.d.ts +13 -0
- package/dist/inbox/memory.js +172 -0
- package/dist/inbox/ports.d.ts +150 -0
- package/dist/inbox/ports.js +1 -0
- package/dist/inbox/redact.d.ts +2 -0
- package/dist/inbox/redact.js +47 -0
- package/dist/inbox/schema.d.ts +1158 -0
- package/dist/inbox/schema.js +90 -0
- package/dist/inbox/watermark.d.ts +13 -0
- package/dist/inbox/watermark.js +6 -0
- package/dist/index.d.ts +20 -0
- package/dist/index.js +18 -0
- package/dist/ledger/ledger.d.ts +47 -0
- package/dist/ledger/ledger.js +224 -0
- package/dist/ports/index.d.ts +2 -0
- package/dist/ports/index.js +1 -0
- package/dist/ports/ledger-store.d.ts +53 -0
- package/dist/ports/ledger-store.js +1 -0
- package/dist/ports/runtime.d.ts +9 -0
- package/dist/ports/runtime.js +1 -0
- package/dist/providers/port.d.ts +201 -0
- package/dist/providers/port.js +30 -0
- package/dist/providers/sepay/index.d.ts +34 -0
- package/dist/providers/sepay/index.js +241 -0
- package/dist/providers/sepay/order.d.ts +32 -0
- package/dist/providers/sepay/order.js +69 -0
- package/dist/providers/sepay/signature.d.ts +8 -0
- package/dist/providers/sepay/signature.js +51 -0
- package/dist/quote/conformance.d.ts +16 -0
- package/dist/quote/conformance.js +39 -0
- package/dist/quote/index.d.ts +3 -0
- package/dist/quote/index.js +3 -0
- package/dist/quote/steps.d.ts +54 -0
- package/dist/quote/steps.js +103 -0
- package/dist/quote/waterfall.d.ts +98 -0
- package/dist/quote/waterfall.js +82 -0
- package/dist/stores/conformance.d.ts +22 -0
- package/dist/stores/conformance.js +269 -0
- package/dist/stores/memory.d.ts +19 -0
- package/dist/stores/memory.js +137 -0
- package/dist/stores/testing.d.ts +11 -0
- package/dist/stores/testing.js +11 -0
- package/docs/API.md +198 -0
- package/docs/SCHEMA.md +108 -0
- package/package.json +75 -4
package/docs/SCHEMA.md
ADDED
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# @tofound/billing — schema factory and migration rules
|
|
2
|
+
|
|
3
|
+
Part of the `billing.schema-factory` contract with
|
|
4
|
+
`src/drizzle/schema-factory.ts`. Checked by `test/contract/schema.test.ts`.
|
|
5
|
+
|
|
6
|
+
## The library ships no SQL
|
|
7
|
+
|
|
8
|
+
Each host owns its migrations. It re-exports the factory tables from a file
|
|
9
|
+
its drizzle-kit `schema` glob already covers, then runs its own `db:generate`:
|
|
10
|
+
|
|
11
|
+
```ts
|
|
12
|
+
// 2novel/api/src/modules/credits/schema.ts
|
|
13
|
+
import { createBillingTables } from '@tofound/billing/drizzle'
|
|
14
|
+
import { uuid } from 'drizzle-orm/pg-core'
|
|
15
|
+
import { translate } from '../../db/schema-namespace'
|
|
16
|
+
import { workspaces } from '../workspace/schema'
|
|
17
|
+
|
|
18
|
+
export const { billingAccounts, billingEntries } = createBillingTables({
|
|
19
|
+
schema: translate,
|
|
20
|
+
prefix: 'billing_',
|
|
21
|
+
accountId: (n) => uuid(n).notNull().references(() => workspaces.id),
|
|
22
|
+
})
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
drizzle-kit loads schema files with CJS `require`. The package is ESM-only;
|
|
26
|
+
every entry also carries a `default` export condition, so that `require`
|
|
27
|
+
resolves through Node's `require(esm)` (unflagged from Node 22.12, the
|
|
28
|
+
package's `engines` floor).
|
|
29
|
+
|
|
30
|
+
`BillingSchemaConfig`:
|
|
31
|
+
|
|
32
|
+
| Option | Default | |
|
|
33
|
+
|---|---|---|
|
|
34
|
+
| `schema` | `public` | a `pgSchema(...)`, e.g. 2Novel `translate` |
|
|
35
|
+
| `prefix` | `billing_` | lower snake case; prefixes tables, indexes and constraints |
|
|
36
|
+
| `accountId` | — | the host-typed subject column (`uuid`, `text` …), NOT NULL, optionally an FK to the host's subject table |
|
|
37
|
+
|
|
38
|
+
## Tables (0.1)
|
|
39
|
+
|
|
40
|
+
`<prefix>accounts` — one row per account, created on first posting.
|
|
41
|
+
|
|
42
|
+
| Column | Type | |
|
|
43
|
+
|---|---|---|
|
|
44
|
+
| `account_id` | host type | PK `<prefix>accounts_pk` |
|
|
45
|
+
| `balance` | bigint not null default 0 | CHECK ≥ 0 |
|
|
46
|
+
| `seq` | bigint not null default 0 | seq of the last entry |
|
|
47
|
+
| `created_at`, `updated_at` | timestamptz | |
|
|
48
|
+
|
|
49
|
+
`<prefix>entries` — append-only ledger.
|
|
50
|
+
|
|
51
|
+
| Column | Type | |
|
|
52
|
+
|---|---|---|
|
|
53
|
+
| `id` | varchar(64) PK | generated by the library |
|
|
54
|
+
| `account_id` | host type | |
|
|
55
|
+
| `seq` | bigint not null | UNIQUE (`account_id`, `seq`) |
|
|
56
|
+
| `delta`, `balance_after` | bigint not null | `balance_after` CHECK ≥ 0 |
|
|
57
|
+
| `kind` | varchar(32) not null | |
|
|
58
|
+
| `reason` | text | host label |
|
|
59
|
+
| `idempotency_key` | text not null | UNIQUE |
|
|
60
|
+
| `source_type`, `source_id` | varchar(64), text | |
|
|
61
|
+
| `reverses_id` | varchar(64) | UNIQUE (NULLs distinct = unique when not null) |
|
|
62
|
+
| `meta` | jsonb | |
|
|
63
|
+
| `created_at` | timestamptz not null | |
|
|
64
|
+
|
|
65
|
+
Inbox, checkout-session, purchase, term and account-token tables are declared
|
|
66
|
+
by their own modules through `billingTableBuilder(config)` — same schema, same
|
|
67
|
+
prefix, same rules — and a host re-exports them beside these.
|
|
68
|
+
|
|
69
|
+
`createIngestTables(config)` (P1) adds `<prefix>inbox` (UNIQUE provider +
|
|
70
|
+
event_id; due index on status + next_attempt_at), `<prefix>checkout_sessions`
|
|
71
|
+
(CHECK amount > 0, credits > 0) and `<prefix>purchases` (UNIQUE provider +
|
|
72
|
+
environment + external_id). `ingestTableNames(prefix)` lists them for
|
|
73
|
+
`checkAdditiveDdl`.
|
|
74
|
+
|
|
75
|
+
## Rules: additive only, never a table rewrite
|
|
76
|
+
|
|
77
|
+
Hosts deploy by migrating the live database before rolling the container, so
|
|
78
|
+
a statement that rewrites or long-locks a table takes production down. Every
|
|
79
|
+
library schema change therefore:
|
|
80
|
+
|
|
81
|
+
1. creates new tables and indexes only;
|
|
82
|
+
2. evolves an existing library table only with a **nullable column without a
|
|
83
|
+
volatile default** (`now()`, `random()`, `gen_random_uuid()` …);
|
|
84
|
+
3. never uses `GENERATED ALWAYS AS (…) STORED`;
|
|
85
|
+
4. never touches a host table (an FK *from* a library table is fine);
|
|
86
|
+
5. adds an index or constraint to an existing library table only
|
|
87
|
+
`CONCURRENTLY` / `NOT VALID` through a host custom migration;
|
|
88
|
+
6. ships as a minor version with a CHANGELOG line telling hosts to `db:generate`.
|
|
89
|
+
|
|
90
|
+
`checkAdditiveDdl(statements, { libraryTables })` returns every violation in
|
|
91
|
+
a generated migration (`generated_stored`, `not_null_add_column`,
|
|
92
|
+
`volatile_default`, `non_library_table`, `destructive`, `blocking_index`,
|
|
93
|
+
`validating_constraint`, `unrecognized`). Hosts can run it on their own
|
|
94
|
+
generated or custom SQL: an element with several `;`-separated statements is
|
|
95
|
+
checked statement by statement, every action of a multi-action `ALTER TABLE`
|
|
96
|
+
is checked, a leading `SET lock_timeout` is allowed, and any shape it does not
|
|
97
|
+
recognise (a dollar-quoted function body, `VACUUM`, …) fails closed as
|
|
98
|
+
`unrecognized`. `ADD PRIMARY KEY` / `UNIQUE` on an existing table is a
|
|
99
|
+
`blocking_index` unless it adopts a concurrently built index (`USING INDEX`).
|
|
100
|
+
|
|
101
|
+
## lock_timeout
|
|
102
|
+
|
|
103
|
+
A host migration that creates or alters library tables must run with
|
|
104
|
+
`SET lock_timeout = '5s'` (the deploy runner sets it, or open the migration
|
|
105
|
+
with it), so a migration that cannot get its lock fails fast instead of
|
|
106
|
+
queueing production behind it. The factory DDL takes locks only on its own new
|
|
107
|
+
tables and, for an FK, a brief `SHARE ROW EXCLUSIVE` on the referenced host
|
|
108
|
+
table; the schema test applies the generated SQL under that timeout.
|
package/package.json
CHANGED
|
@@ -1,6 +1,77 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tofound/billing",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Shared subscription and credit library by 2found: credit ledger, quote/charge waterfall, Drizzle schema factory.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "./dist/index.js",
|
|
7
|
+
"module": "./dist/index.js",
|
|
8
|
+
"types": "./dist/index.d.ts",
|
|
9
|
+
"exports": {
|
|
10
|
+
".": {
|
|
11
|
+
"types": "./dist/index.d.ts",
|
|
12
|
+
"import": "./dist/index.js",
|
|
13
|
+
"default": "./dist/index.js"
|
|
14
|
+
},
|
|
15
|
+
"./drizzle": {
|
|
16
|
+
"types": "./dist/drizzle/index.d.ts",
|
|
17
|
+
"import": "./dist/drizzle/index.js",
|
|
18
|
+
"default": "./dist/drizzle/index.js"
|
|
19
|
+
},
|
|
20
|
+
"./providers/sepay": {
|
|
21
|
+
"types": "./dist/providers/sepay/index.d.ts",
|
|
22
|
+
"import": "./dist/providers/sepay/index.js",
|
|
23
|
+
"default": "./dist/providers/sepay/index.js"
|
|
24
|
+
},
|
|
25
|
+
"./testing": {
|
|
26
|
+
"types": "./dist/stores/testing.d.ts",
|
|
27
|
+
"import": "./dist/stores/testing.js",
|
|
28
|
+
"default": "./dist/stores/testing.js"
|
|
29
|
+
},
|
|
30
|
+
"./package.json": "./package.json"
|
|
31
|
+
},
|
|
32
|
+
"files": [
|
|
33
|
+
"dist",
|
|
34
|
+
"docs/API.md",
|
|
35
|
+
"docs/SCHEMA.md",
|
|
36
|
+
"README.md",
|
|
37
|
+
"CHANGELOG.md",
|
|
38
|
+
"LICENSE"
|
|
39
|
+
],
|
|
40
|
+
"sideEffects": false,
|
|
41
|
+
"engines": {
|
|
42
|
+
"bun": ">=1.3.14",
|
|
43
|
+
"node": ">=22.12"
|
|
44
|
+
},
|
|
45
|
+
"packageManager": "bun@1.3.14",
|
|
46
|
+
"repository": {
|
|
47
|
+
"type": "git",
|
|
48
|
+
"url": "git+https://github.com/2found/2billing.git"
|
|
49
|
+
},
|
|
50
|
+
"publishConfig": {
|
|
51
|
+
"access": "public",
|
|
52
|
+
"registry": "https://registry.npmjs.org/"
|
|
53
|
+
},
|
|
54
|
+
"scripts": {
|
|
55
|
+
"build": "rm -rf dist && tsc -p tsconfig.build.json",
|
|
56
|
+
"typecheck": "tsc --noEmit -p tsconfig.json",
|
|
57
|
+
"test": "bun test",
|
|
58
|
+
"check": "bun run typecheck && bun run build && REQUIRE_PG=1 PACK_SMOKE=1 bun test",
|
|
59
|
+
"prepack": "bun run build"
|
|
60
|
+
},
|
|
61
|
+
"peerDependencies": {
|
|
62
|
+
"drizzle-orm": "^0.45"
|
|
63
|
+
},
|
|
64
|
+
"peerDependenciesMeta": {
|
|
65
|
+
"drizzle-orm": {
|
|
66
|
+
"optional": true
|
|
67
|
+
}
|
|
68
|
+
},
|
|
69
|
+
"devDependencies": {
|
|
70
|
+
"@types/bun": "1.3.14",
|
|
71
|
+
"drizzle-kit": "0.31.11",
|
|
72
|
+
"drizzle-orm": "0.45.4",
|
|
73
|
+
"postgres": "3.4.9",
|
|
74
|
+
"typescript": "5.9.3"
|
|
75
|
+
},
|
|
76
|
+
"license": "UNLICENSED"
|
|
77
|
+
}
|