hyphabase 0.0.1

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 HyphaBase
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,321 @@
1
+ # hyphabase
2
+
3
+ Official JavaScript/TypeScript SDK for [HyphaBase](https://hyphabase.com) — works in React, Next.js, Vue, or any JavaScript app.
4
+
5
+ Auth ships first; every HyphaBase module (clients, employees, schedules, …) will land here over time on the same client.
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ npm install hyphabase
11
+ ```
12
+
13
+ ## Quick start
14
+
15
+ ```ts
16
+ import { createClient } from "hyphabase";
17
+
18
+ const hyphabase = createClient(
19
+ "https://api.hyphabase.com",
20
+ "pk_live_...", // publishable key - safe for the browser
21
+ { locationId: "your-location-uuid" },
22
+ );
23
+ ```
24
+
25
+ ## Auth
26
+
27
+ ```ts
28
+ // Sign up a new end user (application must enable end-user sign-up)
29
+ await hyphabase.auth.signUp({ name, email, password });
30
+
31
+ // Sign in
32
+ await hyphabase.auth.signIn({ email, password });
33
+
34
+ // Session state
35
+ hyphabase.auth.getUser(); // EndUser | null
36
+ hyphabase.auth.getSession(); // Session | null
37
+
38
+ // Sign out (revokes server-side too)
39
+ await hyphabase.auth.signOut();
40
+ ```
41
+
42
+ ### Recovery and verification
43
+
44
+ ```ts
45
+ await hyphabase.auth.forgotPassword({ email }); // emails a single-use token; never says if the address exists
46
+ await hyphabase.auth.resetPassword({ email, token, password }); // revokes every session, including this one
47
+ await hyphabase.auth.verifyEmail({ email, token }); // token arrives at sign-up, or from resendVerification()
48
+ await hyphabase.auth.resendVerification(); // as the signed-in user
49
+ ```
50
+
51
+ Your app hosts the forms; the emails carry the token. If the application requires verification, an unverified user gets `403` with `error.type === "email_unverified"` (`error.isEmailUnverified` in the SDK) on everything except the auth calls above.
52
+
53
+ Every write the SDK makes carries an `Idempotency-Key` (one per call, reused across its own retry), so a request that reaches the API twice is applied once. Pass `idempotencyKey` to `request()` to control it, or `false` to omit it.
54
+
55
+ ### Your profile
56
+
57
+ ```ts
58
+ const { user, permissions } = await hyphabase.profile.get(); // who am I, what may I do here
59
+ await hyphabase.profile.update({ name: "Riley Quinn", email: user.email, phone: "555-0100" }); // name and email are both required: send the current email to keep it
60
+ await hyphabase.profile.changePassword({ current_password, password }); // ends every session, this one included
61
+ const { permissions: mine } = await hyphabase.profile.permissions();
62
+ ```
63
+
64
+ `changePassword` clears the local session because the API revokes every token the person holds: sign in again with the new password.
65
+
66
+ ### Token lifecycle (handled for you)
67
+
68
+ Sessions use a **short-lived access token + rotating refresh token**:
69
+
70
+ - Access tokens expire after ~1 hour; the SDK refreshes them automatically before requests.
71
+ - Every refresh **rotates** the refresh token — the old one is consumed. If a stolen refresh token is ever replayed, the server revokes the entire token family.
72
+ - Concurrent refreshes are coalesced into one request (rotation makes parallel refreshes self-defeating).
73
+ - An unexpected `401` triggers one refresh-and-retry before failing.
74
+
75
+ ## Modules
76
+
77
+ Typed module namespaces live on the client — `clients` is the first:
78
+
79
+ ```ts
80
+ // List, with search + pagination
81
+ const page = await hyphabase.clients.list({ search: "ava", page: 1, perPage: 25 });
82
+ page.data; // Client[]
83
+ page.meta.total; // 42
84
+
85
+ // CRUD
86
+ const ava = await hyphabase.clients.create({
87
+ first_name: "Ava", last_name: "Nguyen",
88
+ email: "ava@example.com", phone: "555-0101",
89
+ });
90
+ await hyphabase.clients.update(ava.id, { phone: "555-9999" });
91
+ await hyphabase.clients.get(ava.id);
92
+ await hyphabase.clients.delete(ava.id);
93
+ await hyphabase.clients.restore(ava.id);
94
+ ```
95
+
96
+ ### Nested resources
97
+
98
+ Notes, traits, and addresses are scoped per client; status definitions and import/export are module-level:
99
+
100
+ ```ts
101
+ const notes = hyphabase.clients.notes(ava.id);
102
+ await notes.create({ category: "general", content: "Prefers oat milk", visibility: "internal" });
103
+ await notes.list();
104
+
105
+ await hyphabase.clients.traits(ava.id).create({ name: "VIP", icon: "star", color: "#f4c04c" });
106
+ await hyphabase.clients.addresses(ava.id).list();
107
+
108
+ await hyphabase.clients.statuses.create({ name: "VIP" });
109
+ await hyphabase.clients.locationStatuses(ava.id).assign(locationId, statusId);
110
+
111
+ const op = await hyphabase.clients.importExport.export({ search: "ava" }); // returns the operation (status "pending")
112
+ // ...poll operations.get(op.id) until it completes, then:
113
+ const csv = await hyphabase.clients.importExport.operations.download(op.id);
114
+ ```
115
+
116
+ Updating a client status is a full update (`PUT`): send its `name` with the change. Notes, traits and addresses update with `PATCH`: only the fields you send change.
117
+
118
+ Employees (staff at the current location) follow the same shape. Deactivating someone keeps their record but stops them signing in; reactivating restores it:
119
+
120
+ ```ts
121
+ const marcus = await hyphabase.employees.create({
122
+ name: "Marcus Lee",
123
+ email: "marcus@glowsalon.example",
124
+ password: "correct horse battery staple",
125
+ });
126
+ await hyphabase.employees.update(marcus.id, { phone: "555-0200" }); // PATCH: only the fields you send change
127
+ await hyphabase.employees.deactivate(marcus.id); // is_active: false
128
+ await hyphabase.employees.reactivate(marcus.id);
129
+ await hyphabase.employees.delete(marcus.id);
130
+ ```
131
+
132
+ Services (the catalog at the current location) take a price and how long they run. `delete` archives; it never rewrites past bookings or invoices:
133
+
134
+ ```ts
135
+ const cut = await hyphabase.services.create({
136
+ name: "Signature cut",
137
+ price: 60,
138
+ duration_minutes: 45,
139
+ buffer_time_minutes: 10,
140
+ });
141
+ await hyphabase.services.update(cut.id, { price: 65 }); // PATCH: only the fields you send change
142
+ await hyphabase.services.delete(cut.id);
143
+ ```
144
+
145
+ Service groups and add-ons are beta: `services.groups.*` works but its shape may change.
146
+
147
+ More modules (schedules, …) will land on the same client over time.
148
+
149
+ ### Roles
150
+
151
+ ```ts
152
+ const role = await hyphabase.organizations.roles.create({ name: "Front desk", permissions: ["clients.view"] });
153
+ await hyphabase.organizations.roles.update(role.id, { name: "Reception" }); // PATCH: only the fields you send change
154
+ const same = await hyphabase.organizations.roles.get(role.id);
155
+ const all = await hyphabase.organizations.roles.list();
156
+ ```
157
+
158
+ ## Calling the API directly
159
+
160
+ `request()` stays available for anything a typed module doesn't cover yet — same auth + location pipeline:
161
+
162
+ ```ts
163
+ const guests = await hyphabase.request("/api/modules/clients");
164
+
165
+ await hyphabase.request("/api/modules/clients", {
166
+ method: "POST",
167
+ body: { first_name: "Ava", last_name: "Nguyen", email: "ava@example.com", phone: "555-0101" },
168
+ });
169
+ ```
170
+
171
+ ## Errors
172
+
173
+ All failures throw `HyphaBaseError` with `status` and the API's response `body` (including `errors` for 422 validation failures):
174
+
175
+ ```ts
176
+ import { HyphaBaseError } from "hyphabase";
177
+
178
+ try {
179
+ await hyphabase.auth.signUp({ name, email, password });
180
+ } catch (err) {
181
+ if (err instanceof HyphaBaseError && err.status === 422) {
182
+ console.log(err.body?.errors); // { email: ["The email has already been taken."] }
183
+ }
184
+ }
185
+ ```
186
+
187
+ ## Custom data (your own collections)
188
+
189
+ Define your own tables — real Postgres tables in a database of their own per environment, with indexes, unique constraints and foreign keys — and read and write records with a secret key. Server-side only in this release.
190
+
191
+ ```ts
192
+ const hb = createClient(url, process.env.HYPHABASE_SECRET_KEY); // data.collections.manage + data.records.*
193
+
194
+ // Schema: field types are fixed for life; everything else can change later.
195
+ await hb.data.collections.create({
196
+ slug: "projects",
197
+ fields: [
198
+ { name: "name", type: "string", required: true, max_length: 200 },
199
+ { name: "status", type: "enum", values: ["active", "done"], default: "active", indexed: true },
200
+ { name: "budget", type: "number", precision: [12, 2] },
201
+ { name: "owner_id", type: "reference", collection: "people", on_delete: "set_null" },
202
+ ],
203
+ });
204
+ await hb.data.collections.update("projects", [{ op: "add_field", name: "due_on", type: "date", indexed: true }]);
205
+ await hb.data.collections.waitUntilReady("projects"); // large tables build indexes in the background
206
+
207
+ // Records: flat payloads, typed with your own shape.
208
+ interface Project { name: string; status: "active" | "done"; budget: number | null; owner_id: string | null; due_on: string | null }
209
+ const projects = hb.data.collection<Project>("projects");
210
+
211
+ const { data: p } = await projects.create({ name: "Website", budget: 1200 });
212
+ await projects.update(p.id, { status: "done" });
213
+ const page = await projects.list({ filter: { status: "active", budget: { gte: 100 } }, sort: "-created_at", limit: 20 });
214
+ for await (const record of projects.iterate({ filter: { status: "done" } })) { /* every page */ }
215
+ await projects.delete(p.id); // soft; restorable; 409 while a `restrict` reference points at it
216
+ ```
217
+
218
+ Keys can be limited to one collection with a suffixed scope (`data.records.read:projects`). Deletes are soft and restorable for 30 days, then real.
219
+
220
+ ## Files
221
+
222
+ Your own files, in the environment's own storage. Bytes go straight to storage
223
+ through a short-lived upload URL - the API only ever sees metadata - and come back
224
+ through an expiring download URL once the virus scan is clean. A custom-data field
225
+ of type `file` holds the id and is a real foreign key.
226
+
227
+ ```ts
228
+ const brief = await hb.files.upload(pdfBytes, {
229
+ name: "spring-brief.pdf",
230
+ contentType: "application/pdf",
231
+ metadata: { kind: "brief" },
232
+ });
233
+
234
+ await hb.files.waitUntilScanned(brief.id); // scan_status: clean
235
+
236
+ await campaigns.create({ name: "Spring", brief: brief.id });
237
+
238
+ const { url, expires_at } = await hb.files.url(brief.id, { expiresIn: 300 });
239
+
240
+ await hb.files.delete(brief.id); // soft; restorable for 30 days
241
+ ```
242
+
243
+ Scopes: `files.read`, `files.upload`, `files.delete`. A file that records point
244
+ at through a `restrict` field refuses deletion with `409` until they let go.
245
+
246
+ ## Webhooks (receiving)
247
+
248
+ Every delivery carries `HyphaBase-Signature: t=<unix>,v1=<hmac>`. Verify over the
249
+ **raw** body with the endpoint's `whsec_` secret before you trust it:
250
+
251
+ ```ts
252
+ import { constructWebhookEvent, WebhookSignatureError } from "hyphabase";
253
+
254
+ app.post("/webhooks/hyphabase", express.raw({ type: "*/*" }), async (req, res) => {
255
+ try {
256
+ const event = await constructWebhookEvent({
257
+ payload: req.body, // Buffer / Uint8Array / string - unparsed
258
+ header: req.header("HyphaBase-Signature"),
259
+ secret: process.env.HYPHABASE_WEBHOOK_SECRET!,
260
+ });
261
+ // event.type, event.data.object
262
+ res.sendStatus(200);
263
+ } catch (err) {
264
+ if (err instanceof WebhookSignatureError) return res.sendStatus(400);
265
+ throw err;
266
+ }
267
+ });
268
+ ```
269
+
270
+ `verifyWebhookSignature()` is the same check without the parse. Both reject stale
271
+ timestamps (5 minutes by default) and compare in constant time; a header with two `v1`
272
+ values (secret rotation) passes if either matches. Needs WebCrypto (Node 18+).
273
+
274
+ ## What the SDK does not do
275
+
276
+ The SDK is for building *applications* on HyphaBase: signing people in and using your modules, custom data and files with an API key. Setting the platform up - your account, applications, environments, locations, API keys, team, billing and webhook endpoints - is done in the console, not here.
277
+
278
+ ## Server-side usage (Node)
279
+
280
+ The same SDK runs on your backend — pass your **secret key** instead:
281
+
282
+ ```ts
283
+ // Node 18+. No session needed: the sk_ key authenticates every request.
284
+ const hb = createClient(url, process.env.HYPHABASE_SECRET_KEY, { locationId });
285
+
286
+ const guests = await hb.clients.list();
287
+ await hb.request("/api/modules/employees/users", { method: "POST", body: { ... } });
288
+ ```
289
+
290
+ The SDK **refuses to construct with an sk_ key in a browser** — a secret key in frontend code is a leaked secret key. Sessions still win when present, so a server acting on behalf of a signed-in user can use both.
291
+
292
+ ## Security model
293
+
294
+ - The **publishable key (`pk_`)** is safe to embed: it can only call the rate-limited sign-up endpoint on applications that opted in, and can read nothing.
295
+ - **Secret keys (`sk_`) must never be used in a browser.** They belong on your server (the SDK throws if you try).
296
+ - End users authenticate with their own credentials; their access is limited by the role your application assigns.
297
+
298
+ ### Where tokens live, honestly
299
+
300
+ By default sessions persist in `localStorage`, which any script running on your page can read — the same default as Supabase and Firebase. The platform's token design is the safety net for that reality:
301
+
302
+ - Access tokens die after ~1 hour; refresh tokens are **single-use** and rotate on every refresh.
303
+ - A stolen refresh token that gets replayed collides with the legitimate session and the server **revokes the whole token family** — the attacker's session dies the moment the real user is next active.
304
+ - Families have an **absolute lifetime** (~30 days from sign-in): a farmed session cannot be kept alive forever, and a **password change revokes everything** immediately.
305
+
306
+ Your real XSS defense is not storage choice — it is a strict Content-Security-Policy and dependency hygiene. If your threat model still rules out persisted tokens, opt out:
307
+
308
+ ```ts
309
+ const hyphabase = createClient(url, pk, {
310
+ locationId,
311
+ persistSession: false, // memory-only: nothing on disk, re-login on page load
312
+ });
313
+ ```
314
+
315
+ ## Development
316
+
317
+ ```bash
318
+ npm install
319
+ npm test # vitest
320
+ npm run build # tsup -> dist/
321
+ ```