@typeb-digital/nucleus-sdk 0.0.1

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@typeb-digital/nucleus-sdk",
+  "version": "0.0.1",
+  "description": "Server-side TypeScript SDK for the Nucleus data platform",
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./dist/cjs/index.cjs",
+  "module": "./dist/es/index.js",
+  "types": "./dist/es/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/es/index.d.ts",
+        "default": "./dist/es/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.cts",
+        "default": "./dist/cjs/index.cjs"
+      }
+    }
+  },
+  "scripts": {
+    "build": "bunchee",
+    "dev": "bunchee --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "ofetch": "1.5.1"
+  },
+  "devDependencies": {
+    "@types/node": "25.9.1",
+    "bunchee": "6.10.0",
+    "typescript": "6.0.3"
+  }
+}

package/src/apps.ts

@@ -0,0 +1,19 @@
+/**
+ * AppsAccessor — wraps the self-service app info endpoint (§3.8, §6).
+ * Calls GET /api/v1/platform/apps/me with the app token.
+ * This is the only platform endpoint accessible via app token.
+ */
+import type { AppInfo, SingleResult, ErrorResult } from './types';
+import type { NucleusTransport } from './transport';
+
+export class AppsAccessor {
+  constructor(private readonly transport: NucleusTransport) {}
+
+  async me(): Promise<SingleResult<AppInfo>> {
+    const result = await this.transport.get<AppInfo>('/api/v1/platform/apps/me');
+
+    if ('error' in result) return result as ErrorResult;
+
+    return { data: result.data };
+  }
+}

package/src/client.ts

@@ -0,0 +1,75 @@
+import type { ScopeDeclaration } from './types';
+import { NucleusTransport } from './transport';
+import { EmployeesAccessor } from './resources/employees';
+import { ProjectsAccessor } from './resources/projects';
+import { ClientsAccessor } from './resources/clients';
+import { PartnersAccessor } from './resources/partners';
+import { DepartmentsAccessor } from './resources/departments';
+import { ProjectTypesAccessor } from './resources/project-types';
+import { CurrenciesAccessor } from './resources/currencies';
+import { GenericRatesAccessor } from './resources/generic-rates';
+import { AppsAccessor } from './apps';
+import { FilesAccessor } from './resources/files';
+
+export type NucleusClientConfig<S extends ScopeDeclaration> = {
+  /** App token — `el_live_...` or `el_test_...`. Store in an environment variable, never commit. */
+  token: string;
+  /** Base URL of the Nucleus API. Defaults to the production platform URL. */
+  baseUrl?: string;
+  /**
+   * Declared scopes — drives the return types of every resource accessor.
+   * Declare exactly the buckets your app token is approved for.
+   * Declaring a bucket the token lacks causes the API to return filtered data;
+   * it does not cause a runtime error during client construction.
+   */
+  scopes: S;
+};
+
+/**
+ * NucleusClient — entry point for the Nucleus server SDK.
+ *
+ * @example
+ * ```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 — it is declared once at
+ * instantiation and drives the return type of every method on the client.
+ * TypeScript infers it automatically; no explicit type parameters needed.
+ */
+export class NucleusClient<const S extends ScopeDeclaration> {
+  readonly employees: EmployeesAccessor<S>;
+  readonly projects: ProjectsAccessor<S>;
+  readonly clients: ClientsAccessor<S>;
+  readonly partners: PartnersAccessor<S>;
+  readonly departments: DepartmentsAccessor<S>;
+  readonly projectTypes: ProjectTypesAccessor<S>;
+  readonly currencies: CurrenciesAccessor<S>;
+  readonly genericRates: GenericRatesAccessor<S>;
+  readonly apps: AppsAccessor;
+  readonly files: FilesAccessor;
+
+  constructor(config: NucleusClientConfig<S>) {
+    const transport = new NucleusTransport(config.token, config.baseUrl);
+
+    this.employees = new EmployeesAccessor<S>(transport);
+    this.projects = new ProjectsAccessor<S>(transport);
+    this.clients = new ClientsAccessor<S>(transport);
+    this.partners = new PartnersAccessor<S>(transport);
+    this.departments = new DepartmentsAccessor<S>(transport);
+    this.projectTypes = new ProjectTypesAccessor<S>(transport);
+    this.currencies = new CurrenciesAccessor<S>(transport);
+    this.genericRates = new GenericRatesAccessor<S>(transport);
+    this.apps = new AppsAccessor(transport);
+    this.files = new FilesAccessor(transport);
+  }
+}

package/src/index.ts

@@ -0,0 +1,82 @@
+export { NucleusClient } from './client';
+export type { NucleusClientConfig } from './client';
+
+// Result types
+export type {
+  ErrorCode,
+  ErrorResult,
+  SuccessResult,
+  ListMeta,
+  ListResult,
+  SingleResult,
+  PaginatedResult,
+} from './types';
+
+// Narrowing helper
+export { isError } from './types';
+
+// Bucket types — re-exported so app code can annotate variables
+export type {
+  EmployeeIdentity,
+  EmployeeContact,
+  EmployeeEmployment,
+  EmployeeSensitive,
+  EmployeeCompensation,
+  EmployeeCompensationHistory,
+  ProjectCore,
+  ProjectTeam,
+  ProjectFinancials,
+  ProjectIntegrations,
+  ProjectMembership,
+  ClientIdentity,
+  ClientContact,
+  ClientFinancials,
+  ClientNotes,
+  PartnerIdentity,
+  PartnerContact,
+  PartnerNotes,
+  DepartmentCore,
+  ProjectTypeCore,
+  CurrencyCore,
+  GenericRateCore,
+  GenericRateFinancials,
+} from './types';
+
+// Scope resolution utilities
+export type {
+  ScopeDeclaration,
+  ResolveEmployee,
+  ResolveProject,
+  ResolveClient,
+  ResolvePartner,
+  ResolveDepartment,
+  ResolveProjectType,
+  ResolveCurrency,
+  ResolveGenericRate,
+} from './types';
+
+// Expand path types
+export type {
+  EmployeeExpandPath,
+  ProjectExpandPath,
+  ClientExpandPath,
+  PartnerExpandPath,
+  WithEmployeeExpand,
+  WithProjectExpand,
+  WithClientExpand,
+  WithPartnerExpand,
+} from './types';
+
+// App info
+export type { AppInfo, AppScopeInfo } from './types';
+
+// File types
+export type {
+  FileVisibility,
+  FileRecord,
+  FileUrlResult,
+  UploadParams,
+  GetUrlOptions,
+  ListParams as FileListParams,
+} from './resources/files';
+export { FilesAccessor } from './resources/files';

package/src/resources/clients.ts

@@ -0,0 +1,65 @@
+import type {
+  ScopeDeclaration,
+  ResolveClient,
+  ClientExpandPath,
+  WithClientExpand,
+  SingleResult,
+  PaginatedResult,
+  ErrorResult,
+} from '../types';
+import type { NucleusTransport } from '../transport';
+import { transformClient } from '../transform';
+
+export type ClientListParams = {
+  search?: string;
+  industry?: string;
+  country?: string;
+  page?: number;
+  pageSize?: number;
+  expand?: readonly ClientExpandPath[];
+};
+
+export class ClientsAccessor<S extends ScopeDeclaration> {
+  constructor(private readonly transport: NucleusTransport) {}
+
+  async list<E extends readonly ClientExpandPath[] = never[]>(
+    params?: ClientListParams & { expand?: E },
+  ): Promise<PaginatedResult<WithClientExpand<ResolveClient<S>, E, S>>> {
+    const query: Record<string, string | number | undefined> = {};
+    if (params?.search) query['search'] = params.search;
+    if (params?.industry) query['industry'] = params.industry;
+    if (params?.country) query['country'] = params.country;
+    if (params?.page) query['page'] = params.page;
+    if (params?.pageSize) query['pageSize'] = params.pageSize;
+    if (params?.expand?.length) query['expand'] = params.expand.join(',');
+
+    const result = await this.transport.getList<unknown>('/api/v1/data/clients', query);
+
+    if ('error' in result) return result as ErrorResult;
+
+    return {
+      data: result.data.map((r) => transformClient(r)) as WithClientExpand<
+        ResolveClient<S>,
+        E,
+        S
+      >[],
+      meta: result.meta,
+    };
+  }
+
+  async getById<E extends readonly ClientExpandPath[] = never[]>(
+    id: string,
+    options?: { expand?: E },
+  ): Promise<SingleResult<WithClientExpand<ResolveClient<S>, E, S>>> {
+    const query: Record<string, string | undefined> = {};
+    if (options?.expand?.length) query['expand'] = options.expand.join(',');
+
+    const result = await this.transport.get<unknown>(`/api/v1/data/clients/${id}`, query);
+
+    if ('error' in result) return result as ErrorResult;
+
+    return {
+      data: transformClient(result.data) as WithClientExpand<ResolveClient<S>, E, S>,
+    };
+  }
+}

package/src/resources/currencies.ts

@@ -0,0 +1,41 @@
+import type {
+  ScopeDeclaration,
+  ResolveCurrency,
+  SingleResult,
+  PaginatedResult,
+  ErrorResult,
+} from '../types';
+import type { NucleusTransport } from '../transport';
+import { transformCurrency } from '../transform';
+
+export type CurrencyListParams = {
+  page?: number;
+  pageSize?: number;
+};
+
+export class CurrenciesAccessor<S extends ScopeDeclaration> {
+  constructor(private readonly transport: NucleusTransport) {}
+
+  async list(params?: CurrencyListParams): Promise<PaginatedResult<ResolveCurrency<S>>> {
+    const query: Record<string, string | number | undefined> = {};
+    if (params?.page) query['page'] = params.page;
+    if (params?.pageSize) query['pageSize'] = params.pageSize;
+
+    const result = await this.transport.getList<unknown>('/api/v1/data/currencies', query);
+
+    if ('error' in result) return result as ErrorResult;
+
+    return {
+      data: result.data.map((r) => transformCurrency(r)) as ResolveCurrency<S>[],
+      meta: result.meta,
+    };
+  }
+
+  async getByCode(code: string): Promise<SingleResult<ResolveCurrency<S>>> {
+    const result = await this.transport.get<unknown>(`/api/v1/data/currencies/${code}`);
+
+    if ('error' in result) return result as ErrorResult;
+
+    return { data: transformCurrency(result.data) as ResolveCurrency<S> };
+  }
+}

package/src/resources/departments.ts

@@ -0,0 +1,43 @@
+import type {
+  ScopeDeclaration,
+  ResolveDepartment,
+  SingleResult,
+  PaginatedResult,
+  ErrorResult,
+} from '../types';
+import type { NucleusTransport } from '../transport';
+import { transformDepartment } from '../transform';
+
+export type DepartmentListParams = {
+  search?: string;
+  page?: number;
+  pageSize?: number;
+};
+
+export class DepartmentsAccessor<S extends ScopeDeclaration> {
+  constructor(private readonly transport: NucleusTransport) {}
+
+  async list(params?: DepartmentListParams): Promise<PaginatedResult<ResolveDepartment<S>>> {
+    const query: Record<string, string | number | undefined> = {};
+    if (params?.search) query['search'] = params.search;
+    if (params?.page) query['page'] = params.page;
+    if (params?.pageSize) query['pageSize'] = params.pageSize;
+
+    const result = await this.transport.getList<unknown>('/api/v1/data/departments', query);
+
+    if ('error' in result) return result as ErrorResult;
+
+    return {
+      data: result.data.map((r) => transformDepartment(r)) as ResolveDepartment<S>[],
+      meta: result.meta,
+    };
+  }
+
+  async getById(id: string): Promise<SingleResult<ResolveDepartment<S>>> {
+    const result = await this.transport.get<unknown>(`/api/v1/data/departments/${id}`);
+
+    if ('error' in result) return result as ErrorResult;
+
+    return { data: transformDepartment(result.data) as ResolveDepartment<S> };
+  }
+}

package/src/resources/employees.ts

@@ -0,0 +1,65 @@
+import type {
+  ScopeDeclaration,
+  ResolveEmployee,
+  EmployeeExpandPath,
+  WithEmployeeExpand,
+  SingleResult,
+  PaginatedResult,
+  ErrorResult,
+} from '../types';
+import type { NucleusTransport } from '../transport';
+import { transformEmployee } from '../transform';
+
+export type EmployeeListParams = {
+  search?: string;
+  department?: string;
+  employmentStatus?: string;
+  page?: number;
+  pageSize?: number;
+  expand?: readonly EmployeeExpandPath[];
+};
+
+export class EmployeesAccessor<S extends ScopeDeclaration> {
+  constructor(private readonly transport: NucleusTransport) {}
+
+  async list<E extends readonly EmployeeExpandPath[] = never[]>(
+    params?: EmployeeListParams & { expand?: E },
+  ): Promise<PaginatedResult<WithEmployeeExpand<ResolveEmployee<S>, E, S>>> {
+    const query: Record<string, string | number | undefined> = {};
+    if (params?.search) query['search'] = params.search;
+    if (params?.department) query['department'] = params.department;
+    if (params?.employmentStatus) query['employmentStatus'] = params.employmentStatus;
+    if (params?.page) query['page'] = params.page;
+    if (params?.pageSize) query['pageSize'] = params.pageSize;
+    if (params?.expand?.length) query['expand'] = params.expand.join(',');
+
+    const result = await this.transport.getList<unknown>('/api/v1/data/employees', query);
+
+    if ('error' in result) return result as ErrorResult;
+
+    return {
+      data: result.data.map((r) => transformEmployee(r)) as WithEmployeeExpand<
+        ResolveEmployee<S>,
+        E,
+        S
+      >[],
+      meta: result.meta,
+    };
+  }
+
+  async getById<E extends readonly EmployeeExpandPath[] = never[]>(
+    id: string,
+    options?: { expand?: E },
+  ): Promise<SingleResult<WithEmployeeExpand<ResolveEmployee<S>, E, S>>> {
+    const query: Record<string, string | undefined> = {};
+    if (options?.expand?.length) query['expand'] = options.expand.join(',');
+
+    const result = await this.transport.get<unknown>(`/api/v1/data/employees/${id}`, query);
+
+    if ('error' in result) return result as ErrorResult;
+
+    return {
+      data: transformEmployee(result.data) as WithEmployeeExpand<ResolveEmployee<S>, E, S>,
+    };
+  }
+}

package/src/resources/files.ts

@@ -0,0 +1,105 @@
+import type { NucleusTransport } from '../transport';
+import type { SingleResult, PaginatedResult, ErrorResult } from '../types';
+
+export type FileVisibility = 'public' | 'private';
+
+export type FileRecord = {
+  id: string;
+  key: string;
+  bucket: string;
+  filename: string | null;
+  mimeType: string;
+  sizeBytes: number;
+  allowedUsers: string[];
+  metadata: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type FileUrlResult = {
+  url: string;
+};
+
+export type UploadParams = {
+  /** App-provided path-style key, e.g. 'users/123/avatar' or 'contracts/2026/q1.pdf'. */
+  key: string;
+  /** File bytes. */
+  file: Buffer;
+  mimeType: string;
+  visibility: FileVisibility;
+  /** Empty or omit → app-wide access. Non-empty restricts to these employee IDs. */
+  allowedUsers?: string[];
+  /** Arbitrary JSON stored alongside the file record. */
+  metadata?: Record<string, unknown>;
+  /** Optional content-disposition filename. Derived from key's last segment if omitted. */
+  filename?: string;
+};
+
+export type GetUrlOptions = {
+  /**
+   * Nucleus user access token (from the client SDK's getSession().accessToken).
+   * Required when the file has allowedUsers — verifies the requesting user is permitted.
+   * Omit for app-wide files.
+   */
+  asUser?: string;
+};
+
+export type ListParams = {
+  /** Filter to files under this path prefix, e.g. 'users/123/'. */
+  prefix?: string;
+  page?: number;
+  pageSize?: number;
+};
+
+export class FilesAccessor {
+  constructor(private readonly transport: NucleusTransport) {}
+
+  /**
+   * Upload a file. Upsert semantics: re-uploading the same key overwrites the
+   * existing R2 object and updates the File record — no duplicate, no error.
+   */
+  async upload(params: UploadParams): Promise<SingleResult<FileRecord> | ErrorResult> {
+    return this.transport.post<FileRecord>('/api/v1/platform/files', {
+      key: params.key,
+      file: params.file.toString('base64'),
+      mimeType: params.mimeType,
+      visibility: params.visibility,
+      ...(params.allowedUsers !== undefined ? { allowedUsers: params.allowedUsers } : {}),
+      ...(params.metadata !== undefined ? { metadata: params.metadata } : {}),
+      ...(params.filename !== undefined ? { filename: params.filename } : {}),
+    });
+  }
+
+  /**
+   * Resolve a usable URL for a file.
+   * - Public files  → deterministic CDN URL
+   * - Private app-wide files → fresh pre-signed URL (expires in R2_SIGNED_URL_TTL seconds)
+   * - Private user-scoped files → supply asUser; 403 if user is not in allowedUsers
+   */
+  async getUrl(
+    key: string,
+    options?: GetUrlOptions,
+  ): Promise<SingleResult<FileUrlResult> | ErrorResult> {
+    return this.transport.post<FileUrlResult>('/api/v1/platform/files/url', {
+      key,
+      ...(options?.asUser ? { asUser: options.asUser } : {}),
+    });
+  }
+
+  /** Soft-delete. Resolution of the key returns 404 thereafter. */
+  async delete(key: string): Promise<SingleResult<null> | ErrorResult> {
+    return this.transport.del<null>('/api/v1/platform/files', { key });
+  }
+
+  /** List this app's files. Optionally filter by path prefix. */
+  async list(params?: ListParams): Promise<PaginatedResult<FileRecord>> {
+    const query: Record<string, string | number | undefined> = {};
+    if (params?.prefix) query['prefix'] = params.prefix;
+    if (params?.page) query['page'] = params.page;
+    if (params?.pageSize) query['pageSize'] = params.pageSize;
+
+    return this.transport.getList<FileRecord>('/api/v1/platform/files', query) as Promise<
+      PaginatedResult<FileRecord>
+    >;
+  }
+}

package/src/resources/generic-rates.ts

@@ -0,0 +1,43 @@
+import type {
+  ScopeDeclaration,
+  ResolveGenericRate,
+  SingleResult,
+  PaginatedResult,
+  ErrorResult,
+} from '../types';
+import type { NucleusTransport } from '../transport';
+import { transformGenericRate } from '../transform';
+
+export type GenericRateListParams = {
+  department?: string;
+  page?: number;
+  pageSize?: number;
+};
+
+export class GenericRatesAccessor<S extends ScopeDeclaration> {
+  constructor(private readonly transport: NucleusTransport) {}
+
+  async list(params?: GenericRateListParams): Promise<PaginatedResult<ResolveGenericRate<S>>> {
+    const query: Record<string, string | number | undefined> = {};
+    if (params?.department) query['department'] = params.department;
+    if (params?.page) query['page'] = params.page;
+    if (params?.pageSize) query['pageSize'] = params.pageSize;
+
+    const result = await this.transport.getList<unknown>('/api/v1/data/generic-rates', query);
+
+    if ('error' in result) return result as ErrorResult;
+
+    return {
+      data: result.data.map((r) => transformGenericRate(r)) as ResolveGenericRate<S>[],
+      meta: result.meta,
+    };
+  }
+
+  async getById(id: string): Promise<SingleResult<ResolveGenericRate<S>>> {
+    const result = await this.transport.get<unknown>(`/api/v1/data/generic-rates/${id}`);
+
+    if ('error' in result) return result as ErrorResult;
+
+    return { data: transformGenericRate(result.data) as ResolveGenericRate<S> };
+  }
+}

package/src/resources/partners.ts

@@ -0,0 +1,61 @@
+import type {
+  ScopeDeclaration,
+  ResolvePartner,
+  PartnerExpandPath,
+  WithPartnerExpand,
+  SingleResult,
+  PaginatedResult,
+  ErrorResult,
+} from '../types';
+import type { NucleusTransport } from '../transport';
+import { transformPartner } from '../transform';
+
+export type PartnerListParams = {
+  search?: string;
+  page?: number;
+  pageSize?: number;
+  expand?: readonly PartnerExpandPath[];
+};
+
+export class PartnersAccessor<S extends ScopeDeclaration> {
+  constructor(private readonly transport: NucleusTransport) {}
+
+  async list<E extends readonly PartnerExpandPath[] = never[]>(
+    params?: PartnerListParams & { expand?: E },
+  ): Promise<PaginatedResult<WithPartnerExpand<ResolvePartner<S>, E, S>>> {
+    const query: Record<string, string | number | undefined> = {};
+    if (params?.search) query['search'] = params.search;
+    if (params?.page) query['page'] = params.page;
+    if (params?.pageSize) query['pageSize'] = params.pageSize;
+    if (params?.expand?.length) query['expand'] = params.expand.join(',');
+
+    const result = await this.transport.getList<unknown>('/api/v1/data/partners', query);
+
+    if ('error' in result) return result as ErrorResult;
+
+    return {
+      data: result.data.map((r) => transformPartner(r)) as WithPartnerExpand<
+        ResolvePartner<S>,
+        E,
+        S
+      >[],
+      meta: result.meta,
+    };
+  }
+
+  async getById<E extends readonly PartnerExpandPath[] = never[]>(
+    id: string,
+    options?: { expand?: E },
+  ): Promise<SingleResult<WithPartnerExpand<ResolvePartner<S>, E, S>>> {
+    const query: Record<string, string | undefined> = {};
+    if (options?.expand?.length) query['expand'] = options.expand.join(',');
+
+    const result = await this.transport.get<unknown>(`/api/v1/data/partners/${id}`, query);
+
+    if ('error' in result) return result as ErrorResult;
+
+    return {
+      data: transformPartner(result.data) as WithPartnerExpand<ResolvePartner<S>, E, S>,
+    };
+  }
+}

package/src/resources/project-types.ts

@@ -0,0 +1,41 @@
+import type {
+  ScopeDeclaration,
+  ResolveProjectType,
+  SingleResult,
+  PaginatedResult,
+  ErrorResult,
+} from '../types';
+import type { NucleusTransport } from '../transport';
+import { transformProjectType } from '../transform';
+
+export type ProjectTypeListParams = {
+  page?: number;
+  pageSize?: number;
+};
+
+export class ProjectTypesAccessor<S extends ScopeDeclaration> {
+  constructor(private readonly transport: NucleusTransport) {}
+
+  async list(params?: ProjectTypeListParams): Promise<PaginatedResult<ResolveProjectType<S>>> {
+    const query: Record<string, string | number | undefined> = {};
+    if (params?.page) query['page'] = params.page;
+    if (params?.pageSize) query['pageSize'] = params.pageSize;
+
+    const result = await this.transport.getList<unknown>('/api/v1/data/project-types', query);
+
+    if ('error' in result) return result as ErrorResult;
+
+    return {
+      data: result.data.map((r) => transformProjectType(r)) as ResolveProjectType<S>[],
+      meta: result.meta,
+    };
+  }
+
+  async getById(id: string): Promise<SingleResult<ResolveProjectType<S>>> {
+    const result = await this.transport.get<unknown>(`/api/v1/data/project-types/${id}`);
+
+    if ('error' in result) return result as ErrorResult;
+
+    return { data: transformProjectType(result.data) as ResolveProjectType<S> };
+  }
+}