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 +21 -0
- package/README.md +321 -0
- package/dist/index.cjs +1056 -0
- package/dist/index.d.cts +1242 -0
- package/dist/index.d.ts +1242 -0
- package/dist/index.js +1008 -0
- package/package.json +49 -0
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
|
+
```
|