@typeb-digital/nucleus-sdk 0.0.1 → 0.0.3

package/README.md

@@ -0,0 +1,236 @@
+# @typeb-digital/nucleus-sdk
+
+Server-side TypeScript SDK for the **Nucleus data platform** — the company source of truth for people, projects, and clients.
+
+Install this in your **app backend** (Node.js). It holds the app token and handles all data access. Never import it in browser code.
+
+---
+
+## Installation
+
+```bash
+npm install @typeb-digital/nucleus-sdk
+# or
+yarn add @typeb-digital/nucleus-sdk
+```
+
+Requires Node.js ≥ 18.
+
+---
+
+## Quick start
+
+```typescript
+import { NucleusClient } from '@typeb-digital/nucleus-sdk';
+
+export const nucleus = new NucleusClient({
+  token: process.env.NUCLEUS_TOKEN!,
+  scopes: {
+    employees: ['identity', 'employment'],
+    projects: ['core'],
+    clients: ['identity'],
+  },
+});
+```
+
+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.
+
+> **Get your token and init script** from the Nucleus dashboard → Apps → your app → Init Script.
+
+---
+
+## Scopes & buckets
+
+Nucleus groups fields into **buckets** per resource. Your app only receives fields for the buckets you've been approved for.
+
+| Resource       | Available buckets                                                                                |
+| -------------- | ------------------------------------------------------------------------------------------------ |
+| `employees`    | `identity` · `contact` · `employment` · `sensitive`¹ · `compensation`¹ · `compensation_history`¹ |
+| `projects`     | `core` · `team` · `financials` · `integrations`                                                  |
+| `clients`      | `identity` · `contact` · `financials` · `notes`                                                  |
+| `partners`     | `identity` · `contact` · `notes`                                                                 |
+| `departments`  | `core`                                                                                           |
+| `projectTypes` | `core`                                                                                           |
+| `currencies`   | `core`                                                                                           |
+| `genericRates` | `core` · `financials`¹                                                                           |
+
+¹ Requires platform-team approval.
+
+---
+
+## Data access
+
+### Employees
+
+```typescript
+// List — type reflects declared buckets
+const result = await nucleus.employees.list({
+  department: 'Engineering',
+  page: 1,
+  pageSize: 50,
+});
+
+if (!isError(result)) {
+  result.data; // Employee[] typed to your scopes
+  result.meta.total; // number
+  result.meta.hasMore; // boolean
+}
+
+// Single record
+const { data: emp } = await nucleus.employees.getById('emp_123');
+
+// With expansion — manager is typed as an Employee object, not just a string ID
+const { data: emp } = await nucleus.employees.getById('emp_123', {
+  expand: ['manager'],
+});
+if (emp.manager) {
+  emp.manager.email; // ✓ typed
+}
+```
+
+### Projects
+
+```typescript
+const result = await nucleus.projects.list({ status: 'active' });
+
+// Expand client and team members in one call
+const { data: project } = await nucleus.projects.getById('proj_123', {
+  expand: ['client', 'projectManager', 'memberships.employee'],
+});
+```
+
+### Clients, Partners, Departments, Currencies, Generic Rates
+
+Same pattern — `list(params?)` and `getById(id, options?)` on every resource accessor.
+
+---
+
+## Result type
+
+Every method returns a result object — **never throws** by default:
+
+```typescript
+import { NucleusClient, isError } from '@typeb-digital/nucleus-sdk';
+
+const result = await nucleus.employees.getById('emp_123');
+
+if (isError(result)) {
+  // result.error.code: 'FORBIDDEN' | 'NOT_FOUND' | 'INVALID_SCOPE' | 'RATE_LIMITED' | 'NETWORK_ERROR'
+  console.error(result.error.message);
+  return;
+}
+
+// result.data is fully typed here
+console.log(result.data.email);
+```
+
+---
+
+## File storage
+
+```typescript
+// Upload — app provides a path-style key; upsert semantics
+const { data: file } = await nucleus.files.upload({
+  key: 'users/123/avatar',
+  file: buffer, // Buffer
+  mimeType: 'image/png',
+  visibility: 'private',
+  allowedUsers: ['emp_123'], // optional — omit for app-wide access
+  metadata: { type: 'avatar' },
+});
+
+// Resolve a URL to pass to your frontend
+// Public  → CDN URL (instant, no signing)
+// Private → fresh short-lived pre-signed URL
+const { data } = await nucleus.files.getUrl('users/123/avatar');
+// data.url — hand this to the browser
+
+// Private file scoped to a specific user
+const { data } = await nucleus.files.getUrl('users/123/avatar', {
+  asUser: userAccessToken, // from the client SDK's getSession().accessToken
+});
+
+// List files
+const result = await nucleus.files.list({ prefix: 'users/123/' });
+
+// Soft delete
+await nucleus.files.delete('users/123/avatar');
+```
+
+---
+
+## Self-service app info
+
+```typescript
+const { data: app } = await nucleus.apps.me();
+// app.name, app.scopes (declared), app.status per-bucket
+```
+
+---
+
+## Pagination
+
+All `list()` methods return explicit pagination metadata:
+
+```typescript
+const result = await nucleus.employees.list({ page: 2, pageSize: 25 });
+
+if (!isError(result)) {
+  result.meta.total; // total records
+  result.meta.page; // current page
+  result.meta.pageSize; // records per page
+  result.meta.hasMore; // boolean shortcut
+}
+```
+
+---
+
+## Expansion
+
+Related records are not included by default. Request them explicitly:
+
+```typescript
+// Depth 1
+const { data } = await nucleus.projects.getById('proj_123', {
+  expand: ['client', 'projectManager'],
+});
+
+// Depth 2 (max)
+const { data } = await nucleus.projects.getById('proj_123', {
+  expand: ['projectManager.manager'],
+});
+```
+
+Valid expand paths per resource are typed — invalid paths or three-segment paths are compile errors.
+
+---
+
+## TypeScript
+
+The SDK is fully typed with no `any`. Bucket scopes drive the return types at compile time:
+
+```typescript
+// scopes.employees = ['identity'] only
+const { data: emp } = await nucleus.employees.getById('emp_123');
+emp.email; // ✓ string
+emp.phone; // ✗ compile error — contact bucket not declared
+emp.managerId; // ✗ compile error — employment bucket not declared
+```
+
+---
+
+## Configuration
+
+```typescript
+new NucleusClient({
+  token:   process.env.NUCLEUS_TOKEN!,  // required
+  baseUrl: 'https://nucleus.example.com', // optional, defaults to platform URL
+  scopes:  { ... },                      // required
+})
+```
+
+---
+
+## License
+
+MIT — Type B Digital