@typeb-digital/nucleus-sdk 0.0.5 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+All notable changes to `@typeb-digital/nucleus-sdk` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
+project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). While the
+package is pre-`1.0.0`, **breaking changes may land in a minor version** (e.g. `0.0.x` → `0.1.0`).
+
+## [0.1.0] - 2026-06-22
+
+Action-typed scopes and write support. **This is a breaking release** — every consumer's
+`scopes` config must be migrated (see _Migration_ below).
+
+### Changed
+
+- **BREAKING — `scopes` is now per-action.** Each resource declares an object of action →
+  buckets instead of a flat bucket array:
+
+  ```diff
+    new NucleusClient({
+      token: process.env.NUCLEUS_TOKEN!,
+      scopes: {
+  -     employees: ['identity', 'employment'],
+  -     leaves: ['core'],
+  +     employees: { read: ['identity', 'employment'], update: ['contact'] },
+  +     leaves: { read: ['core'], create: ['core'], delete: true },
+      },
+    });
+  ```
+
+  `read` drives the return types of `list()` / `getById()` (unchanged behaviour, just nested
+  under `read`). `create` / `update` are bucket lists; `delete` is a boolean.
+
+### Added
+
+- **Mutation methods** on writable resources: `create(data)`, `update(id, data)`, and
+  `delete(id)`. They are **gated at compile time by the declared scope** — calling
+  `nucleus.leaves.create(...)` is a type error unless `leaves.create` is declared. The
+  platform also enforces the same per-bucket authorization at runtime (`INVALID_SCOPE`).
+  Mutations return the same `SingleResult<T>` shape as reads and never throw; `delete`
+  returns `{ data: null }`.
+- **Test sandbox tokens.** An `el_test_` token reads/writes the anonymized test sandbox; an
+  `el_live_` token hits real data once the app is published. The token prefix is the only
+  switch — no SDK config change.
+
+### Fixed
+
+- **`apps.me()` (`AppInfo`) realigned with the API.** Each token now carries `mode`
+  (`'live'` | `'test'`); added the publish-lifecycle fields `status`, `submittedAt`,
+  `publishedAt`, `reviewNote`, and `redirectUris`.
+
+### Removed
+
+- **BREAKING — `AppInfo.environment` and `tokens[].environment`.** The platform dropped the
+  `environment` concept; a token's environment is now its `mode`. (The fields had been
+  returning `undefined` at runtime since the platform change.)
+
+### Migration
+
+1. Wrap each resource's bucket array in `{ read: [...] }`.
+2. Add `create` / `update` / `delete` only for the actions your app token is approved for —
+   the dashboard's **Init Script** generates the correct config.
+3. Replace any reads of `app.environment` / `token.environment` with `token.mode`.
+
+## [0.0.x] - Initial development
+
+Pre-`0.1.0` releases (read-only data access). These were not individually version-tagged;
+this entry summarizes the surface that existed before `0.1.0`:
+
+### Added
+
+- `NucleusClient` with compile-time scope→type inference (bucket arrays).
+- Read accessors (`list` / `getById`, with `expand`) for: employees, projects, clients,
+  partners, departments, projectTypes, currencies, genericRates, jurisdictions, leaveTypes,
+  leaves, leaveBalances, policies, policyAcknowledgements, calendarEvents, timesheets.
+- `files` accessor (R2-backed) including `getUrl({ asUser })` for user-scoped private files.
+- `auth.verifyToken()` (RS256 / JWKS) for the dual-token (app + forwarded user token) model.
+- `apps.me()` self-service app info, including the normalized `permissions[]` rows plus the
+  back-compat aggregated `scopes[]`.
+- `isError()` result-narrowing helper; results never throw.

package/README.md

@@ -96,16 +96,18 @@ async function projectHandler(req, res) {
 import { NucleusClient } from '@typeb-digital/nucleus-sdk';
 
 export const nucleus = new NucleusClient({
-  token: process.env.NUCLEUS_TOKEN!,
+  token: process.env.NUCLEUS_TOKEN!, // el_live_… or el_test_… (sandbox)
   scopes: {
-    employees: ['identity', 'employment'],
-    projects: ['core'],
-    clients: ['identity'],
+    employees: { read: ['identity', 'employment'], update: ['contact'] },
+    projects: { read: ['core'] },
+    leaves: { read: ['core'], create: ['core'], delete: true },
   },
 });
 ```
 
-The `scopes` object is the heart of the type system. Declare it once; every method on the client returns types that reflect exactly those buckets — nothing more, nothing less. TypeScript infers the types automatically; no explicit type parameters needed.
+The `scopes` object is the heart of the type system. Each resource declares its **per-action** buckets — `read`, `create`, `update` (each a bucket list) and `delete` (boolean). `read` drives the return types of `list`/`getById`; `create`/`update`/`delete` **gate the mutation methods at compile time** — calling `nucleus.leaves.create(...)` is a type error unless you declared `leaves.create`. Declare it once; TypeScript infers everything, no explicit type parameters needed.
+
+> **Test vs live:** the token _is_ the environment — an `el_test_` token reads/writes the anonymized sandbox; an `el_live_` token hits real data (once your app is published). No SDK config change.
 
 > **Get your token and init script** from the Nucleus dashboard → Apps → your app → Init Script.
 
@@ -130,6 +132,31 @@ Nucleus groups fields into **buckets** per resource. Your app only receives fiel
 
 ---
 
+## Writing data (mutations)
+
+Resources you've scoped for `create` / `update` / `delete` expose matching methods. They're **gated by your declared scope** — the method is uncallable unless the action is declared, so you can't even construct a call the server would reject.
+
+```typescript
+// Requires `leaves: { create: [...] }`
+const created = await nucleus.leaves.create({
+  employeeId: 'emp_…',
+  leaveTypeId: 'lt_…',
+  startDate: '2026-07-01',
+  endDate: '2026-07-03',
+  days: 3,
+});
+
+// Requires `leaves: { update: [...] }`
+await nucleus.leaves.update('leave_…', { days: 2 });
+
+// Requires `leaves: { delete: true }`
+await nucleus.leaves.delete('leave_…');
+```
+
+All mutations return the same `SingleResult<T>` shape as reads (`{ data }` or `{ error }`) — they never throw. `delete` returns `{ data: null }`. The server enforces the same per-bucket authorization independently, so an unapproved write fails with `INVALID_SCOPE` even if the types allowed it.
+
+---
+
 ## Data access
 
 ### Employees