@typeb-digital/nucleus-sdk 0.0.1 → 0.0.3

package/src/types.ts

@@ -1,447 +0,0 @@
-/**
- * Nucleus SDK — Type System
- *
- * Bucket types are transcribed from docs/NUCLEUS_PIVOT.md §7 (Bucket Definitions).
- * Each bucket type contains only that bucket's fields.
- * The scope-to-type inference intersects selected bucket types at compile time.
- */
-
-// ─── Utility types ────────────────────────────────────────────────────────────
-
-// Converts a union to an intersection: A | B → A & B
-export type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (
-  k: infer I,
-) => void
-  ? I
-  : never;
-
-// Returned when a resource has no declared scopes — accessing any field is a compile error
-export type NoScope = Record<never, never>;
-
-// ─── Result types (§3.5) ─────────────────────────────────────────────────────
-
-export type ErrorCode =
-  | 'FORBIDDEN'
-  | 'NOT_FOUND'
-  | 'INVALID_SCOPE'
-  | 'RATE_LIMITED'
-  | 'NETWORK_ERROR';
-
-export type ErrorResult = {
-  error: { code: ErrorCode; message: string };
-};
-
-export type SuccessResult<T> = { data: T };
-
-export type ListMeta = {
-  total: number;
-  page: number;
-  pageSize: number;
-  hasMore: boolean;
-};
-
-export type ListResult<T> = { data: T[]; meta: ListMeta };
-
-export type SingleResult<T> = SuccessResult<T> | ErrorResult;
-export type PaginatedResult<T> = ListResult<T> | ErrorResult;
-
-export function isError<T>(
-  result: SuccessResult<T> | ListResult<T> | ErrorResult,
-): result is ErrorResult {
-  return 'error' in result;
-}
-
-// ─── §7.1  Employees — bucket types ──────────────────────────────────────────
-
-export type EmployeeIdentity = {
-  id: string;
-  displayName: string;
-  firstName: string;
-  lastName: string;
-  email: string;
-  pictureUrl: string | null;
-  jobTitle: string | null;
-  department: string | null;
-  employmentStatus: string;
-  isExternal: boolean;
-};
-
-export type EmployeeContact = {
-  profile: {
-    phone?: string | null;
-    city?: string | null;
-    country?: string | null;
-  };
-};
-
-export type EmployeeEmployment = {
-  startDate: string | null;
-  weeklyCapacity: number | null;
-  managerId: string | null;
-  partnerId: string | null;
-  /** IANA timezone string, e.g. "Asia/Colombo". Null when not yet set. */
-  timezone: string | null;
-  profile: {
-    biography?: string | null;
-  };
-};
-
-export type EmployeeSensitive = {
-  birthday: string | null;
-  profile: {
-    emergencyContact?: {
-      name: string | null;
-      phone: string | null;
-    } | null;
-  };
-  customFields: Record<string, unknown> | null;
-};
-
-export type EmployeeCompensation = {
-  currentCompensation: {
-    hourlyCostRate: number | null;
-    hourlyBillableRate: number | null;
-    monthlyCostRate: number | null;
-    monthlyBillableRate: number | null;
-    currencyCode: string;
-    effectiveFrom: string;
-  } | null;
-};
-
-export type EmployeeCompensationHistory = {
-  compensationHistory: Array<{
-    hourlyCostRate: number | null;
-    hourlyBillableRate: number | null;
-    monthlyCostRate: number | null;
-    monthlyBillableRate: number | null;
-    currencyCode: string;
-    effectiveFrom: string;
-    effectiveTo: string | null;
-  }>;
-};
-
-export type EmployeeBucketMap = {
-  identity: EmployeeIdentity;
-  contact: EmployeeContact;
-  employment: EmployeeEmployment;
-  sensitive: EmployeeSensitive;
-  compensation: EmployeeCompensation;
-  compensation_history: EmployeeCompensationHistory;
-};
-
-// ─── §7.2  Projects — bucket types ───────────────────────────────────────────
-
-export type ProjectMembership = {
-  employeeId: string;
-  role: string | null;
-};
-
-export type ProjectCore = {
-  id: string;
-  name: string;
-  status: string;
-  colorTag: string | null;
-  iconName: string | null;
-  startDate: string | null;
-  endDate: string | null;
-  projectTypeId: string | null;
-  clientId: string | null;
-};
-
-export type ProjectTeam = {
-  projectManagerId: string | null;
-  engagementLeadId: string | null;
-  memberships: ProjectMembership[];
-};
-
-export type ProjectFinancials = Record<never, never>; // reserved — no fields yet
-
-export type ProjectIntegrations = {
-  source: string | null;
-  clockifyProjectId: string | null;
-  clockifyWorkspaceId: string | null;
-  apolloDealId: string | null;
-};
-
-export type ProjectBucketMap = {
-  core: ProjectCore;
-  team: ProjectTeam;
-  financials: ProjectFinancials;
-  integrations: ProjectIntegrations;
-};
-
-// ─── §7.3  Clients — bucket types ────────────────────────────────────────────
-
-export type ClientIdentity = {
-  id: string;
-  name: string;
-  code: string | null;
-  industry: string | null;
-  website: string | null;
-  country: string | null;
-};
-
-export type ClientContact = {
-  primaryContactName: string | null;
-  primaryContactEmail: string | null;
-  contactPhone: string | null;
-};
-
-export type ClientFinancials = {
-  defaultCurrency: string | null;
-};
-
-export type ClientNotes = {
-  notes: string | null;
-};
-
-export type ClientBucketMap = {
-  identity: ClientIdentity;
-  contact: ClientContact;
-  financials: ClientFinancials;
-  notes: ClientNotes;
-};
-
-// ─── §7.4  Partners — bucket types ───────────────────────────────────────────
-
-export type PartnerIdentity = {
-  id: string;
-  name: string;
-};
-
-export type PartnerContact = {
-  contactName: string | null;
-  contactEmail: string | null;
-  contactPhone: string | null;
-};
-
-export type PartnerNotes = {
-  notes: string | null;
-};
-
-export type PartnerBucketMap = {
-  identity: PartnerIdentity;
-  contact: PartnerContact;
-  notes: PartnerNotes;
-};
-
-// ─── §7.5  Departments ───────────────────────────────────────────────────────
-
-export type DepartmentCore = {
-  id: string;
-  name: string;
-  titles: string[];
-  sortOrder: number;
-};
-
-export type DepartmentBucketMap = {
-  core: DepartmentCore;
-};
-
-// ─── §7.6  Project Types ─────────────────────────────────────────────────────
-
-export type ProjectTypeCore = {
-  id: string;
-  name: string;
-  description: string | null;
-  sortOrder: number;
-};
-
-export type ProjectTypeBucketMap = {
-  core: ProjectTypeCore;
-};
-
-// ─── §7.7  Currencies ────────────────────────────────────────────────────────
-
-export type CurrencyCore = {
-  code: string;
-  name: string;
-  symbol: string | null;
-  isDefault: boolean;
-  sortOrder: number;
-};
-
-export type CurrencyBucketMap = {
-  core: CurrencyCore;
-};
-
-// ─── §7.8  Generic Rates ─────────────────────────────────────────────────────
-
-export type GenericRateCore = {
-  id: string;
-  title: string;
-  department: string;
-  currencyCode: string;
-};
-
-export type GenericRateFinancials = {
-  costRate: number;
-  billableRate: number;
-};
-
-export type GenericRateBucketMap = {
-  core: GenericRateCore;
-  financials: GenericRateFinancials;
-};
-
-// ─── Scope declaration ────────────────────────────────────────────────────────
-
-export type ScopeDeclaration = {
-  employees?: readonly (keyof EmployeeBucketMap)[];
-  projects?: readonly (keyof ProjectBucketMap)[];
-  clients?: readonly (keyof ClientBucketMap)[];
-  partners?: readonly (keyof PartnerBucketMap)[];
-  departments?: readonly (keyof DepartmentBucketMap)[];
-  projectTypes?: readonly (keyof ProjectTypeBucketMap)[];
-  currencies?: readonly (keyof CurrencyBucketMap)[];
-  genericRates?: readonly (keyof GenericRateBucketMap)[];
-};
-
-// ─── Scope resolution ────────────────────────────────────────────────────────
-//
-// ResolveBuckets<BucketMap, Buckets> intersects the bucket types selected by
-// the developer. When no scopes are declared, returns NoScope so that accessing
-// any field is a compile-time error.
-
-type ResolveBuckets<M, B> = B extends readonly (keyof M)[]
-  ? [B[number]] extends [never]
-    ? NoScope
-    : UnionToIntersection<M[B[number]]>
-  : NoScope;
-
-export type ResolveEmployee<S extends ScopeDeclaration> = ResolveBuckets<
-  EmployeeBucketMap,
-  S['employees']
->;
-
-export type ResolveProject<S extends ScopeDeclaration> = ResolveBuckets<
-  ProjectBucketMap,
-  S['projects']
->;
-
-export type ResolveClient<S extends ScopeDeclaration> = ResolveBuckets<
-  ClientBucketMap,
-  S['clients']
->;
-
-export type ResolvePartner<S extends ScopeDeclaration> = ResolveBuckets<
-  PartnerBucketMap,
-  S['partners']
->;
-
-export type ResolveDepartment<S extends ScopeDeclaration> = ResolveBuckets<
-  DepartmentBucketMap,
-  S['departments']
->;
-
-export type ResolveProjectType<S extends ScopeDeclaration> = ResolveBuckets<
-  ProjectTypeBucketMap,
-  S['projectTypes']
->;
-
-export type ResolveCurrency<S extends ScopeDeclaration> = ResolveBuckets<
-  CurrencyBucketMap,
-  S['currencies']
->;
-
-export type ResolveGenericRate<S extends ScopeDeclaration> = ResolveBuckets<
-  GenericRateBucketMap,
-  S['genericRates']
->;
-
-// ─── Expand paths (§3.7, §7) — max two levels, no three-segment paths ────────
-
-export type EmployeeExpandPath = 'manager' | 'partner';
-
-// Expand contributions added to the base employee type
-export type WithEmployeeExpand<
-  T,
-  E extends readonly EmployeeExpandPath[],
-  S extends ScopeDeclaration,
-> = T &
-  ('manager' extends E[number] ? { manager: ResolveEmployee<S> | null } : unknown) &
-  ('partner' extends E[number] ? { partner: PartnerIdentity | null } : unknown);
-
-export type ProjectExpandPath =
-  | 'projectType'
-  | 'client'
-  | 'projectManager'
-  | 'projectManager.manager'
-  | 'engagementLead'
-  | 'engagementLead.manager'
-  | 'memberships.employee';
-
-// Expand contributions for projects. Handles depth-2 paths by nesting manager.
-// memberships.employee overrides the memberships[] type to include employee.
-type ProjectMembershipExpanded<S extends ScopeDeclaration> = {
-  employeeId: string;
-  role: string | null;
-  employee: ResolveEmployee<S>;
-};
-
-export type WithProjectExpand<
-  T,
-  E extends readonly ProjectExpandPath[],
-  S extends ScopeDeclaration,
-> = ('memberships.employee' extends E[number]
-  ? Omit<T, 'memberships'> & { memberships: Array<ProjectMembershipExpanded<S>> }
-  : T) &
-  ('client' extends E[number] ? { client: ResolveClient<S> | null } : unknown) &
-  ('projectType' extends E[number] ? { projectType: ProjectTypeCore | null } : unknown) &
-  ('projectManager.manager' extends E[number]
-    ? { projectManager: (ResolveEmployee<S> & { manager: ResolveEmployee<S> | null }) | null }
-    : 'projectManager' extends E[number]
-      ? { projectManager: ResolveEmployee<S> | null }
-      : unknown) &
-  ('engagementLead.manager' extends E[number]
-    ? { engagementLead: (ResolveEmployee<S> & { manager: ResolveEmployee<S> | null }) | null }
-    : 'engagementLead' extends E[number]
-      ? { engagementLead: ResolveEmployee<S> | null }
-      : unknown);
-
-export type ClientExpandPath = 'projects';
-
-export type WithClientExpand<
-  T,
-  E extends readonly ClientExpandPath[],
-  S extends ScopeDeclaration,
-> = T & ('projects' extends E[number] ? { projects: Array<ResolveProject<S>> } : unknown);
-
-export type PartnerExpandPath = 'employees';
-
-export type WithPartnerExpand<
-  T,
-  E extends readonly PartnerExpandPath[],
-  S extends ScopeDeclaration,
-> = T & ('employees' extends E[number] ? { employees: Array<ResolveEmployee<S>> } : unknown);
-
-// ─── apps.me() response ──────────────────────────────────────────────────────
-
-export type AppScopeInfo = {
-  id: string;
-  resource: string;
-  buckets: string[];
-  status: 'active' | 'pending' | 'rejected';
-  reviewNote: string | null;
-};
-
-export type AppInfo = {
-  id: string;
-  appId: string;
-  name: string;
-  description: string | null;
-  icon: string | null;
-  environment: string;
-  status: string;
-  scopes: AppScopeInfo[];
-  tokens: {
-    id: string;
-    tokenPrefix: string;
-    environment: string;
-    status: string;
-    lastUsedAt: string | null;
-    expiresAt: string | null;
-    createdAt: string;
-  }[];
-  createdAt: string;
-};

package/tsconfig.json

@@ -1,12 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "compilerOptions": {
-    "module": "CommonJS",
-    "moduleResolution": "node",
-    "outDir": "dist",
-    "rootDir": "src",
-    "types": ["node"],
-    "noUncheckedIndexedAccess": false
-  },
-  "include": ["src"]
-}

package/tsconfig.verify.json

@@ -1,11 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "compilerOptions": {
-    "module": "CommonJS",
-    "moduleResolution": "node",
-    "types": ["node"],
-    "noUncheckedIndexedAccess": false,
-    "noEmit": true
-  },
-  "include": ["src", "verify.ts"]
-}

package/verify.ts

@@ -1,182 +0,0 @@
-/**
- * Compile-time type verification for the Nucleus SDK.
- *
- * This file is never executed — it only needs to pass `tsc --noEmit`.
- * Each block demonstrates an expected compile-time behaviour.
- * Lines marked @ts-expect-error MUST produce a type error; if they don't,
- * the check fails.
- */
-
-import { NucleusClient, isError, type ResolveEmployee, type ScopeDeclaration } from './src/index';
-
-// ─── 1. identity-only scope ──────────────────────────────────────────────────
-
-declare const nucleus1: NucleusClient<{
-  employees: ['identity'];
-}>;
-
-async function check1() {
-  const result = await nucleus1.employees.getById('emp_123');
-  if (isError(result)) return;
-
-  const emp = result.data;
-
-  // identity fields — must be accessible
-  const _email: string = emp.email;
-  const _displayName: string = emp.displayName;
-  const _id: string = emp.id;
-
-  // @ts-expect-error — 'phone' is in the contact bucket, not declared
-  const _phone = emp.phone;
-
-  // @ts-expect-error — 'managerId' is in the employment bucket, not declared
-  const _mgr = emp.managerId;
-
-  // @ts-expect-error — 'birthday' is in the sensitive bucket, not declared
-  const _bday = emp.birthday;
-}
-
-// ─── 2. identity + employment scope ─────────────────────────────────────────
-
-declare const nucleus2: NucleusClient<{
-  employees: ['identity', 'employment'];
-}>;
-
-async function check2() {
-  const result = await nucleus2.employees.getById('emp_123');
-  if (isError(result)) return;
-
-  const emp = result.data;
-
-  // both buckets accessible
-  const _email: string = emp.email;
-  const _managerId: string | null = emp.managerId;
-  const _weeklyCapacity: number | null = emp.weeklyCapacity;
-
-  // @ts-expect-error — still no contact scope
-  const _phone = emp.phone;
-}
-
-// ─── 3. expand: ['manager'] changes type ─────────────────────────────────────
-
-declare const nucleus3: NucleusClient<{
-  employees: ['identity', 'employment'];
-}>;
-
-async function check3() {
-  const result = await nucleus3.employees.getById('emp_123', {
-    expand: ['manager'],
-  });
-  if (isError(result)) return;
-
-  const emp = result.data;
-
-  // manager is now an object (or null) — not just a managerId string
-  if (emp.manager) {
-    const _mgrEmail: string = emp.manager.email;
-    const _mgrName: string = emp.manager.displayName;
-  }
-}
-
-// ─── 4. three-segment expand path is a compile error ────────────────────────
-
-declare const nucleus4: NucleusClient<{
-  projects: ['core', 'team'];
-  employees: ['identity'];
-  clients: ['identity'];
-}>;
-
-async function check4() {
-  await nucleus4.projects.getById('proj_123', {
-    // @ts-expect-error — 'client.projects.something' has 3 segments → not a valid ProjectExpandPath
-    expand: ['client.projects.something'],
-  });
-
-  // Two-segment paths are valid
-  const result = await nucleus4.projects.getById('proj_123', {
-    expand: ['projectManager', 'projectManager.manager'],
-  });
-  if (isError(result)) return;
-
-  const proj = result.data;
-  if (proj.projectManager) {
-    const _name: string = proj.projectManager.displayName;
-    if (proj.projectManager.manager) {
-      const _mgrName: string = proj.projectManager.manager.displayName;
-    }
-  }
-}
-
-// ─── 5. list() returns meta with hasMore ─────────────────────────────────────
-
-declare const nucleus5: NucleusClient<{ employees: ['identity'] }>;
-
-async function check5() {
-  const result = await nucleus5.employees.list({ page: 1, pageSize: 20 });
-  if (isError(result)) return;
-
-  const _total: number = result.meta.total;
-  const _hasMore: boolean = result.meta.hasMore;
-  const _page: number = result.meta.page;
-}
-
-// ─── 6. isError() narrow helper ──────────────────────────────────────────────
-
-declare const nucleus6: NucleusClient<{ employees: ['identity'] }>;
-
-async function check6() {
-  const result = await nucleus6.employees.getById('emp_x');
-
-  if (isError(result)) {
-    // code is typed, not just string
-    const _code: 'FORBIDDEN' | 'NOT_FOUND' | 'INVALID_SCOPE' | 'RATE_LIMITED' | 'NETWORK_ERROR' =
-      result.error.code;
-    return;
-  }
-
-  // TypeScript knows result.data is available here
-  const _id: string = result.data.id;
-}
-
-// ─── 7. apps.me() return type ────────────────────────────────────────────────
-
-declare const nucleus7: NucleusClient<{}>;
-
-async function check7() {
-  const result = await nucleus7.apps.me();
-  if (isError(result)) return;
-
-  const _name: string = result.data.name;
-  const _scopes = result.data.scopes; // AppScopeInfo[]
-  const _status = _scopes[0]?.status; // 'active' | 'pending' | 'rejected' | undefined
-}
-
-// ─── 8. no scope declared → NoScope type ────────────────────────────────────
-
-declare const nucleus8: NucleusClient<{}>;
-
-async function check8() {
-  const result = await nucleus8.employees.getById('emp_x');
-  if (isError(result)) return;
-
-  // @ts-expect-error — no employees scope declared at all
-  const _email = result.data.email;
-}
-
-// ─── 9. type helper: ResolveEmployee ─────────────────────────────────────────
-
-type S = { employees: ['identity', 'compensation'] };
-type Emp = ResolveEmployee<S>;
-// Should have identity fields
-type _hasId = Emp extends { id: string } ? true : false; // true
-type _hasComp = Emp extends { currentCompensation: unknown } ? true : false; // true
-
-// ─── Suppress unused-variable warnings ───────────────────────────────────────
-void check1;
-void check2;
-void check3;
-void check4;
-void check5;
-void check6;
-void check7;
-void check8;