@reopt-ai/brandapp-sdk 3.0.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 (76) hide show
  1. package/CHANGELOG.md +574 -0
  2. package/LICENSE +21 -0
  3. package/README.md +468 -0
  4. package/dist/ai/index.d.ts +314 -0
  5. package/dist/ai/index.js +7 -0
  6. package/dist/ai-provider/index.d.ts +196 -0
  7. package/dist/ai-provider/index.js +703 -0
  8. package/dist/auth/index.d.ts +76 -0
  9. package/dist/auth/index.js +40 -0
  10. package/dist/better-auth/client.d.ts +29 -0
  11. package/dist/better-auth/client.js +10 -0
  12. package/dist/better-auth/index.d.ts +82 -0
  13. package/dist/better-auth/index.js +145 -0
  14. package/dist/chunk-6FLYVNZI.js +32 -0
  15. package/dist/chunk-6KPKZ7ZB.js +49 -0
  16. package/dist/chunk-DI6QJPTQ.js +449 -0
  17. package/dist/chunk-E457LO5A.js +599 -0
  18. package/dist/chunk-F7BXBTZI.js +54 -0
  19. package/dist/chunk-J5Y2GSJF.js +443 -0
  20. package/dist/chunk-K3YVJE6E.js +96 -0
  21. package/dist/chunk-KU2LN5SE.js +350 -0
  22. package/dist/chunk-L4DHB36G.js +75 -0
  23. package/dist/chunk-PJZB4VP7.js +63 -0
  24. package/dist/chunk-REIKXSMY.js +7 -0
  25. package/dist/chunk-T2WXHAAC.js +54 -0
  26. package/dist/chunk-TUKIYH4Q.js +112 -0
  27. package/dist/chunk-WSEROZVO.js +81 -0
  28. package/dist/chunk-YRGLBM6V.js +157 -0
  29. package/dist/client-BkcO-0C2.d.ts +216 -0
  30. package/dist/client-CN5_tNOC.d.ts +147 -0
  31. package/dist/client-DttyeM_h.d.ts +102 -0
  32. package/dist/cms/index.d.ts +137 -0
  33. package/dist/cms/index.js +101 -0
  34. package/dist/config-CtxyJsDR.d.ts +397 -0
  35. package/dist/dev/index.d.ts +509 -0
  36. package/dist/dev/index.js +3071 -0
  37. package/dist/eav/coerce.d.ts +42 -0
  38. package/dist/eav/coerce.js +65 -0
  39. package/dist/eav/index.d.ts +214 -0
  40. package/dist/eav/index.js +147 -0
  41. package/dist/eav/migrate.d.ts +236 -0
  42. package/dist/eav/migrate.js +219 -0
  43. package/dist/eav/schema.d.ts +260 -0
  44. package/dist/eav/schema.js +656 -0
  45. package/dist/errors-5hd5ZR-M.d.ts +158 -0
  46. package/dist/feedback/index.d.ts +132 -0
  47. package/dist/feedback/index.js +5 -0
  48. package/dist/files/index.d.ts +54 -0
  49. package/dist/files/index.js +31 -0
  50. package/dist/index.d.ts +221 -0
  51. package/dist/index.js +84 -0
  52. package/dist/plans/index.d.ts +140 -0
  53. package/dist/plans/index.js +5 -0
  54. package/dist/push/index.d.ts +79 -0
  55. package/dist/push/index.js +5 -0
  56. package/dist/react/hooks.d.ts +376 -0
  57. package/dist/react/hooks.js +421 -0
  58. package/dist/terms/index.d.ts +79 -0
  59. package/dist/terms/index.js +5 -0
  60. package/dist/testing/index.d.ts +154 -0
  61. package/dist/testing/index.js +81 -0
  62. package/dist/typed-client-BxOVIiMU.d.ts +40 -0
  63. package/dist/types-6E3ZLL9X.d.ts +24 -0
  64. package/dist/types-DskYLVb8.d.ts +104 -0
  65. package/dist/types-ckmDDW3N.d.ts +129 -0
  66. package/dist/webhooks/index.d.ts +140 -0
  67. package/dist/webhooks/index.js +142 -0
  68. package/docs/api-reference.md +557 -0
  69. package/docs/cms.md +318 -0
  70. package/docs/dev-server.md +164 -0
  71. package/docs/environment.md +211 -0
  72. package/docs/errors.md +290 -0
  73. package/docs/files.md +272 -0
  74. package/docs/migration.md +315 -0
  75. package/docs/testing.md +163 -0
  76. package/package.json +173 -0
@@ -0,0 +1,236 @@
1
+ import { A as AttributeDef, p as EntityDef } from '../config-CtxyJsDR.js';
2
+ import { R as ReoptEavClient } from '../client-BkcO-0C2.js';
3
+ import '../typed-client-BxOVIiMU.js';
4
+
5
+ /**
6
+ * Subset of `ReoptEavClient.records` exposed inside a migration's `up`/`down`.
7
+ *
8
+ * The migrate runner pins these methods to a specific entity-id at call time,
9
+ * so consumer code reads naturally (`records.backfill(entity, ...)`).
10
+ */
11
+ type MigrationRecordsClient = Pick<ReoptEavClient["records"], "list" | "listAll" | "count" | "create" | "update" | "upsert" | "delete" | "bulkCreate" | "bulkUpdate" | "bulkDelete" | "deleteWhere" | "findOne" | "backfill">;
12
+ /**
13
+ * Schema mutation surface available inside a migration.
14
+ *
15
+ * All operations resolve entities/attributes by *name* (the same identifier
16
+ * used inside the user's `eav.schema.ts`). The runner translates names to IDs
17
+ * by querying the server entity list — the migration itself never deals in
18
+ * UUIDs.
19
+ */
20
+ type MigrationSchemaClient = {
21
+ /** Add a new entity. Fails if an entity with the same name already exists. */
22
+ addEntity(name: string, def: Omit<EntityDef, "name" | "attributes">): Promise<void>;
23
+ /** Delete an entity (and all its attributes/records). */
24
+ removeEntity(name: string): Promise<void>;
25
+ /** Add a new attribute to an entity. */
26
+ addAttribute(entity: string, name: string, def: AttributeDef): Promise<void>;
27
+ /** Delete an attribute and all its values. */
28
+ removeAttribute(entity: string, name: string): Promise<void>;
29
+ /** Rename an attribute, preserving values. */
30
+ renameAttribute(entity: string, oldName: string, newName: string): Promise<void>;
31
+ };
32
+ /**
33
+ * Context object passed to a migration's `up`/`down` function.
34
+ */
35
+ type MigrationContext = {
36
+ schema: MigrationSchemaClient;
37
+ records: MigrationRecordsClient;
38
+ /** Structured log channel — runner pipes this to CLI output. */
39
+ log: (msg: string) => void;
40
+ };
41
+ type MigrationDirection = "up" | "down";
42
+ type MigrationFn = (ctx: MigrationContext) => Promise<void>;
43
+ type MigrationSpec = {
44
+ /**
45
+ * Stable migration name. Convention: matches the file name without
46
+ * extension and timestamp suffix (`20260427120000_rename_tier_to_level`).
47
+ */
48
+ name: string;
49
+ /** Forward migration. Required. */
50
+ up: MigrationFn;
51
+ /**
52
+ * Optional reverse migration. Forward-only is the recommended default —
53
+ * only declare `down` for trivially invertible changes.
54
+ */
55
+ down?: MigrationFn;
56
+ };
57
+ type Migration = MigrationSpec & {
58
+ readonly __brand: "ReoptEavMigration";
59
+ };
60
+ type AppliedMigrationRecord = {
61
+ id: string;
62
+ brandappId: string;
63
+ name: string;
64
+ checksum: string;
65
+ appliedAt: string;
66
+ appliedBy: string | null;
67
+ durationMs: number | null;
68
+ };
69
+ type MigrationStatus = {
70
+ state: "pending";
71
+ name: string;
72
+ } | {
73
+ state: "applied";
74
+ name: string;
75
+ checksum: string;
76
+ appliedAt: string;
77
+ } | {
78
+ state: "drift";
79
+ name: string;
80
+ localChecksum: string;
81
+ serverChecksum: string;
82
+ appliedAt: string;
83
+ };
84
+ type MigrationRunResult = {
85
+ /** Migration name that was just applied. */
86
+ name: string;
87
+ /** SHA-256 checksum of the file content. */
88
+ checksum: string;
89
+ /** Wall-clock duration of the `up` function in milliseconds. */
90
+ durationMs: number;
91
+ /** True when the runner skipped because the migration was already applied. */
92
+ alreadyApplied: boolean;
93
+ };
94
+ /**
95
+ * One schema-level operation captured during a batched migration run.
96
+ *
97
+ * Mirrors `apps/web/server/hono/routes/brandapp-migrations-schemas.ts`'s
98
+ * `MigrationOperation`. Sent to `POST /v1/brandapp/{id}/migrations/apply`
99
+ * where the server applies the whole array inside a single
100
+ * `prisma.$transaction` (Phase A.5 atomicity, RFC-0005 ADR-2).
101
+ *
102
+ * `records.*` calls are NOT represented here — they execute immediately and
103
+ * outside the transaction.
104
+ */
105
+ type MigrationOperation = {
106
+ kind: "addEntity";
107
+ name: string;
108
+ def?: {
109
+ description?: string | null;
110
+ icon?: string | null;
111
+ linkedTo?: "brandapp" | "brandappAuthUser";
112
+ };
113
+ } | {
114
+ kind: "removeEntity";
115
+ name: string;
116
+ } | {
117
+ kind: "addAttribute";
118
+ entity: string;
119
+ name: string;
120
+ def: AttributeDef;
121
+ } | {
122
+ kind: "removeAttribute";
123
+ entity: string;
124
+ name: string;
125
+ } | {
126
+ kind: "renameAttribute";
127
+ entity: string;
128
+ oldName: string;
129
+ newName: string;
130
+ };
131
+
132
+ /**
133
+ * Branded factory for a forward (and optional reverse) EAV schema migration.
134
+ *
135
+ * @example
136
+ * ```ts
137
+ * import { defineMigration } from "@reopt-ai/brandapp-sdk/eav/migrate";
138
+ *
139
+ * export default defineMigration({
140
+ * name: "rename_tier_to_level",
141
+ * up: async ({ schema, records }) => {
142
+ * await schema.addAttribute("contacts", "level", {
143
+ * dataType: "string",
144
+ * label: "Level",
145
+ * });
146
+ * await records.backfill("contacts", {
147
+ * transform: (r) => ({ level: r.values.tier ?? "free" }),
148
+ * });
149
+ * await schema.removeAttribute("contacts", "tier");
150
+ * },
151
+ * });
152
+ * ```
153
+ */
154
+ declare function defineMigration(spec: MigrationSpec): Migration;
155
+ /** Type guard — returns true when `value` was produced by `defineMigration`. */
156
+ declare function isMigration(value: unknown): value is Migration;
157
+
158
+ type CreateMigrationContextOptions = {
159
+ /** Override the log channel. Defaults to no-op (runner pipes through). */
160
+ log?: (msg: string) => void;
161
+ };
162
+ /**
163
+ * Build the `MigrationContext` consumed by `migration.up`/`down`.
164
+ *
165
+ * Wraps an existing `ReoptEavClient`:
166
+ * - `schema.*` operates on entity/attribute *names*, resolving to IDs lazily.
167
+ * - `records.*` is a strict subset of `eav.records` (read + mutate by ID).
168
+ * - `log` is whatever the caller passes (CLI prints, dev server captures).
169
+ */
170
+ declare function createMigrationContext(eav: ReoptEavClient, opts?: CreateMigrationContextOptions): MigrationContext;
171
+
172
+ type RunMigrationOptions = {
173
+ /** Direction — defaults to `up`. `down` requires `migration.down` to exist. */
174
+ direction?: MigrationDirection;
175
+ /** Pre-computed SHA-256 of the migration file. Surfaced in the result. */
176
+ checksum: string;
177
+ /**
178
+ * Hook called whenever the migration emits `ctx.log(...)`. Defaults to
179
+ * a no-op so the SDK stays quiet by default; the CLI plugs in a printer.
180
+ */
181
+ onLog?: (msg: string) => void;
182
+ /**
183
+ * Acquire/release a server-side advisory lock around the run. Phase 3 first
184
+ * PR ships **no** real lock — the runner just calls these hooks if provided.
185
+ * The next PR wires them into the server.
186
+ */
187
+ lock?: {
188
+ acquire: () => Promise<void>;
189
+ release: () => Promise<void>;
190
+ };
191
+ };
192
+ /**
193
+ * Execute a single migration's `up` (or `down`) function.
194
+ *
195
+ * Pure SDK-level — does NOT record applied state on the server. The CLI
196
+ * (`reopt brandapp eav migrate run`) is responsible for calling
197
+ * `client.migrations.create(...)` after `runMigration` resolves.
198
+ *
199
+ * Splitting "execute the function" from "record the row" lets the dev server
200
+ * + tests reuse the runner without touching a remote audit log.
201
+ */
202
+ declare function runMigration(eav: ReoptEavClient, migration: Migration, opts: RunMigrationOptions): Promise<MigrationRunResult>;
203
+ type CollectMigrationOptions = {
204
+ /** Defaults to `up`. */
205
+ direction?: MigrationDirection;
206
+ /** Forwarded to `ctx.log`. */
207
+ onLog?: (msg: string) => void;
208
+ };
209
+ type CollectMigrationResult = {
210
+ /** Schema operations captured from `ctx.schema.*` calls, in invocation order. */
211
+ operations: MigrationOperation[];
212
+ /** Wall-clock duration of the `up` function (ms). */
213
+ durationMs: number;
214
+ };
215
+ /**
216
+ * Run a migration's `up`/`down` function with a buffering schema client so
217
+ * the consumer can apply the whole operation set atomically (e.g. via the
218
+ * server's `POST /v1/brandapp/{id}/migrations/apply` route, which wraps the
219
+ * whole array in a single `prisma.$transaction`).
220
+ *
221
+ * Key differences vs. `runMigration`:
222
+ * - **Schema ops are buffered, not sent.** The returned `operations` array
223
+ * is the only side effect on the schema layer.
224
+ * - **Records.* still execute immediately.** Backfills run against the
225
+ * *current* server state — they cannot read attributes that this
226
+ * migration is about to create. If a backfill depends on a new attribute,
227
+ * place it in a follow-up migration.
228
+ * - **No checksum / lock plumbing.** Audit + lock are the caller's job
229
+ * (CLI handles both today).
230
+ *
231
+ * Introduced by Phase A.5 (RFC-0005 ADR-2). The legacy `runMigration` is
232
+ * retained for callers that have not yet adopted the batch endpoint.
233
+ */
234
+ declare function runMigrationCollecting(eav: ReoptEavClient, migration: Migration, opts?: CollectMigrationOptions): Promise<CollectMigrationResult>;
235
+
236
+ export { type AppliedMigrationRecord, type CollectMigrationOptions, type CollectMigrationResult, type CreateMigrationContextOptions, type Migration, type MigrationContext, type MigrationDirection, type MigrationFn, type MigrationOperation, type MigrationRecordsClient, type MigrationRunResult, type MigrationSchemaClient, type MigrationSpec, type MigrationStatus, type RunMigrationOptions, createMigrationContext, defineMigration, isMigration, runMigration, runMigrationCollecting };
@@ -0,0 +1,219 @@
1
+ // src/eav/migrate/define.ts
2
+ function defineMigration(spec) {
3
+ if (!spec || typeof spec !== "object") {
4
+ throw new Error("defineMigration: spec must be an object");
5
+ }
6
+ if (typeof spec.name !== "string" || spec.name.trim().length === 0) {
7
+ throw new Error("defineMigration: `name` must be a non-empty string");
8
+ }
9
+ if (typeof spec.up !== "function") {
10
+ throw new Error(
11
+ `defineMigration("${spec.name}"): \`up\` must be an async function`
12
+ );
13
+ }
14
+ if (spec.down !== void 0 && typeof spec.down !== "function") {
15
+ throw new Error(
16
+ `defineMigration("${spec.name}"): \`down\` must be an async function when provided`
17
+ );
18
+ }
19
+ return {
20
+ name: spec.name,
21
+ up: spec.up,
22
+ down: spec.down,
23
+ __brand: "ReoptEavMigration"
24
+ };
25
+ }
26
+ function isMigration(value) {
27
+ return typeof value === "object" && value !== null && value.__brand === "ReoptEavMigration";
28
+ }
29
+
30
+ // src/eav/migrate/context.ts
31
+ async function findEntityIdByName(eav, entityName) {
32
+ const entities = await eav.entities.list();
33
+ const match = entities.find((e) => e.name === entityName);
34
+ if (!match) {
35
+ throw new Error(
36
+ `Migration: entity "${entityName}" not found on server. Use schema.addEntity() first or check the entity name.`
37
+ );
38
+ }
39
+ return match.id;
40
+ }
41
+ async function findAttributeIdByName(eav, entityId, attributeName) {
42
+ const detail = await eav.entities.get(entityId);
43
+ const attr = detail.attributes.find((a) => a.name === attributeName);
44
+ if (!attr) {
45
+ throw new Error(
46
+ `Migration: attribute "${attributeName}" not found on entity ${entityId}.`
47
+ );
48
+ }
49
+ return attr.id;
50
+ }
51
+ function createSchemaClient(eav, log) {
52
+ return {
53
+ async addEntity(name, def) {
54
+ log(`addEntity ${name}`);
55
+ await eav.entities.create({
56
+ name,
57
+ description: def.description,
58
+ icon: def.icon
59
+ });
60
+ },
61
+ async removeEntity(name) {
62
+ log(`removeEntity ${name}`);
63
+ const id = await findEntityIdByName(eav, name);
64
+ await eav.entities.delete(id);
65
+ },
66
+ async addAttribute(entity, name, def) {
67
+ log(`addAttribute ${entity}.${name} (${def.dataType})`);
68
+ const entityId = await findEntityIdByName(eav, entity);
69
+ await eav.attributes.create(entityId, {
70
+ name,
71
+ label: def.label,
72
+ dataType: def.dataType,
73
+ isRequired: def.isRequired,
74
+ isUnique: def.isUnique,
75
+ defaultValue: def.defaultValue,
76
+ validation: def.validation,
77
+ options: def.options ? [...def.options] : void 0,
78
+ sortOrder: def.sortOrder
79
+ });
80
+ },
81
+ async removeAttribute(entity, name) {
82
+ log(`removeAttribute ${entity}.${name}`);
83
+ const entityId = await findEntityIdByName(eav, entity);
84
+ const attrId = await findAttributeIdByName(eav, entityId, name);
85
+ await eav.attributes.delete(entityId, attrId);
86
+ },
87
+ async renameAttribute(entity, oldName, newName) {
88
+ log(`renameAttribute ${entity}.${oldName} \u2192 ${newName}`);
89
+ const entityId = await findEntityIdByName(eav, entity);
90
+ const attrId = await findAttributeIdByName(eav, entityId, oldName);
91
+ await eav.attributes.update(entityId, attrId, { name: newName });
92
+ }
93
+ };
94
+ }
95
+ function createRecordsClient(eav) {
96
+ return {
97
+ list: eav.records.list,
98
+ listAll: eav.records.listAll,
99
+ count: eav.records.count,
100
+ create: eav.records.create,
101
+ update: eav.records.update,
102
+ upsert: eav.records.upsert,
103
+ delete: eav.records.delete,
104
+ bulkCreate: eav.records.bulkCreate,
105
+ bulkUpdate: eav.records.bulkUpdate,
106
+ bulkDelete: eav.records.bulkDelete,
107
+ deleteWhere: eav.records.deleteWhere,
108
+ findOne: eav.records.findOne,
109
+ backfill: eav.records.backfill
110
+ };
111
+ }
112
+ function createMigrationContext(eav, opts = {}) {
113
+ const log = opts.log ?? (() => {
114
+ });
115
+ return {
116
+ schema: createSchemaClient(eav, log),
117
+ records: createRecordsClient(eav),
118
+ log
119
+ };
120
+ }
121
+
122
+ // src/eav/migrate/runner.ts
123
+ async function runMigration(eav, migration, opts) {
124
+ if (!isMigration(migration)) {
125
+ throw new Error(
126
+ `runMigration: expected a migration created with defineMigration(), got ${typeof migration}`
127
+ );
128
+ }
129
+ const direction = opts.direction ?? "up";
130
+ const fn = direction === "up" ? migration.up : migration.down;
131
+ if (!fn) {
132
+ throw new Error(
133
+ `runMigration("${migration.name}"): no \`${direction}\` function defined`
134
+ );
135
+ }
136
+ const log = opts.onLog ?? (() => {
137
+ });
138
+ const ctx = createMigrationContext(eav, { log });
139
+ if (opts.lock) await opts.lock.acquire();
140
+ const startedAt = Date.now();
141
+ try {
142
+ log(`\u25B6 ${migration.name} (${direction})`);
143
+ await fn(ctx);
144
+ const durationMs = Date.now() - startedAt;
145
+ log(`\u2713 ${migration.name} (${direction}) \u2014 ${durationMs}ms`);
146
+ return {
147
+ name: migration.name,
148
+ checksum: opts.checksum,
149
+ durationMs,
150
+ alreadyApplied: false
151
+ };
152
+ } finally {
153
+ if (opts.lock) {
154
+ await opts.lock.release().catch(() => void 0);
155
+ }
156
+ }
157
+ }
158
+ async function runMigrationCollecting(eav, migration, opts = {}) {
159
+ if (!isMigration(migration)) {
160
+ throw new Error(
161
+ `runMigrationCollecting: expected a migration created with defineMigration(), got ${typeof migration}`
162
+ );
163
+ }
164
+ const direction = opts.direction ?? "up";
165
+ const fn = direction === "up" ? migration.up : migration.down;
166
+ if (!fn) {
167
+ throw new Error(
168
+ `runMigrationCollecting("${migration.name}"): no \`${direction}\` function defined`
169
+ );
170
+ }
171
+ const log = opts.onLog ?? (() => {
172
+ });
173
+ const operations = [];
174
+ const schema = {
175
+ async addEntity(name, def) {
176
+ operations.push({ kind: "addEntity", name, def });
177
+ log(`buffer addEntity ${name}`);
178
+ },
179
+ async removeEntity(name) {
180
+ operations.push({ kind: "removeEntity", name });
181
+ log(`buffer removeEntity ${name}`);
182
+ },
183
+ async addAttribute(entity, name, def) {
184
+ operations.push({ kind: "addAttribute", entity, name, def });
185
+ log(`buffer addAttribute ${entity}.${name} (${def.dataType})`);
186
+ },
187
+ async removeAttribute(entity, name) {
188
+ operations.push({ kind: "removeAttribute", entity, name });
189
+ log(`buffer removeAttribute ${entity}.${name}`);
190
+ },
191
+ async renameAttribute(entity, oldName, newName) {
192
+ operations.push({
193
+ kind: "renameAttribute",
194
+ entity,
195
+ oldName,
196
+ newName
197
+ });
198
+ log(`buffer renameAttribute ${entity}.${oldName} \u2192 ${newName}`);
199
+ }
200
+ };
201
+ const ctx = createMigrationContext(eav, { log });
202
+ const collectingCtx = {
203
+ schema,
204
+ records: ctx.records,
205
+ log
206
+ };
207
+ const startedAt = Date.now();
208
+ log(`\u25B6 ${migration.name} (${direction}, collecting)`);
209
+ await fn(collectingCtx);
210
+ const durationMs = Date.now() - startedAt;
211
+ log(
212
+ `\u2713 ${migration.name} (${direction}, collecting) \u2014 ${operations.length} op(s) in ${durationMs}ms`
213
+ );
214
+ return { operations, durationMs };
215
+ }
216
+
217
+ export { createMigrationContext, defineMigration, isMigration, runMigration, runMigrationCollecting };
218
+ //# sourceMappingURL=migrate.js.map
219
+ //# sourceMappingURL=migrate.js.map