@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.
Files changed (68) hide show
  1. package/CHANGELOG.md +46 -0
  2. package/LICENSE +3 -0
  3. package/README.md +34 -2
  4. package/dist/domain/errors.d.ts +14 -0
  5. package/dist/domain/errors.js +21 -0
  6. package/dist/domain/money.d.ts +21 -0
  7. package/dist/domain/money.js +77 -0
  8. package/dist/domain/types.d.ts +165 -0
  9. package/dist/domain/types.js +18 -0
  10. package/dist/drizzle/index.d.ts +3 -0
  11. package/dist/drizzle/index.js +3 -0
  12. package/dist/drizzle/schema-factory.d.ts +586 -0
  13. package/dist/drizzle/schema-factory.js +206 -0
  14. package/dist/drizzle/store.d.ts +20 -0
  15. package/dist/drizzle/store.js +124 -0
  16. package/dist/inbox/apply.d.ts +48 -0
  17. package/dist/inbox/apply.js +299 -0
  18. package/dist/inbox/conformance.d.ts +20 -0
  19. package/dist/inbox/conformance.js +254 -0
  20. package/dist/inbox/drizzle.d.ts +14 -0
  21. package/dist/inbox/drizzle.js +203 -0
  22. package/dist/inbox/ingest.d.ts +108 -0
  23. package/dist/inbox/ingest.js +404 -0
  24. package/dist/inbox/memory.d.ts +13 -0
  25. package/dist/inbox/memory.js +172 -0
  26. package/dist/inbox/ports.d.ts +150 -0
  27. package/dist/inbox/ports.js +1 -0
  28. package/dist/inbox/redact.d.ts +2 -0
  29. package/dist/inbox/redact.js +47 -0
  30. package/dist/inbox/schema.d.ts +1158 -0
  31. package/dist/inbox/schema.js +90 -0
  32. package/dist/inbox/watermark.d.ts +13 -0
  33. package/dist/inbox/watermark.js +6 -0
  34. package/dist/index.d.ts +20 -0
  35. package/dist/index.js +18 -0
  36. package/dist/ledger/ledger.d.ts +47 -0
  37. package/dist/ledger/ledger.js +224 -0
  38. package/dist/ports/index.d.ts +2 -0
  39. package/dist/ports/index.js +1 -0
  40. package/dist/ports/ledger-store.d.ts +53 -0
  41. package/dist/ports/ledger-store.js +1 -0
  42. package/dist/ports/runtime.d.ts +9 -0
  43. package/dist/ports/runtime.js +1 -0
  44. package/dist/providers/port.d.ts +201 -0
  45. package/dist/providers/port.js +30 -0
  46. package/dist/providers/sepay/index.d.ts +34 -0
  47. package/dist/providers/sepay/index.js +241 -0
  48. package/dist/providers/sepay/order.d.ts +32 -0
  49. package/dist/providers/sepay/order.js +69 -0
  50. package/dist/providers/sepay/signature.d.ts +8 -0
  51. package/dist/providers/sepay/signature.js +51 -0
  52. package/dist/quote/conformance.d.ts +16 -0
  53. package/dist/quote/conformance.js +39 -0
  54. package/dist/quote/index.d.ts +3 -0
  55. package/dist/quote/index.js +3 -0
  56. package/dist/quote/steps.d.ts +54 -0
  57. package/dist/quote/steps.js +103 -0
  58. package/dist/quote/waterfall.d.ts +98 -0
  59. package/dist/quote/waterfall.js +82 -0
  60. package/dist/stores/conformance.d.ts +22 -0
  61. package/dist/stores/conformance.js +269 -0
  62. package/dist/stores/memory.d.ts +19 -0
  63. package/dist/stores/memory.js +137 -0
  64. package/dist/stores/testing.d.ts +11 -0
  65. package/dist/stores/testing.js +11 -0
  66. package/docs/API.md +198 -0
  67. package/docs/SCHEMA.md +108 -0
  68. 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.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
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
+ }