@zergai/zergbox-client 0.1.0

package/index.d.ts

@@ -0,0 +1,211 @@
+export type SyncNodeType = 'directory' | 'file'
+
+export interface SyncNode {
+  id: string
+  path: string
+  type: SyncNodeType
+  revision?: number
+  contentHash?: string
+  sizeBytes?: number
+  updatedAt?: string
+}
+
+export type SyncChangeType =
+  | 'create_remote_folder'
+  | 'move_remote_folder'
+  | 'upload_file'
+  | 'move_remote_file'
+  | 'create_local_folder'
+  | 'move_local_folder'
+  | 'download_file'
+  | 'move_local_file'
+  | 'conflict'
+  | 'delete_remote'
+  | 'delete_remote_folder'
+  | 'delete_local'
+  | 'delete_local_folder'
+
+export interface SyncChange {
+  type: SyncChangeType
+  path: string
+  fromPath?: string
+  reason?: string
+  remoteId?: string
+}
+
+export type MergeCandidateState = 'pending' | 'resolved' | 'dismissed'
+
+export interface MergeCandidate {
+  id: string
+  path: string
+  state: MergeCandidateState
+  base?: SyncNode
+  local: SyncNode
+  remote: SyncNode
+  createdAt?: string
+}
+
+export const SYNC_NODE_TYPES: readonly SyncNodeType[]
+export const SYNC_CHANGE_TYPES: readonly SyncChangeType[]
+export const MERGE_CANDIDATE_STATES: readonly MergeCandidateState[]
+
+export function isSyncNode(value: unknown): value is SyncNode
+export function isSyncChange(value: unknown): value is SyncChange
+export function isMergeCandidate(value: unknown): value is MergeCandidate
+
+export interface ZergBoxClientOptions {
+  baseUrl: string
+  token: string
+  requestTimeoutMs?: number
+  maxResponseBytes?: number
+  maxDownloadBytes?: number
+}
+
+export interface ZergBoxOrganization {
+  id: string
+  name: string
+  slug?: string
+}
+
+export interface ZergBoxFolder {
+  id: string
+  name: string
+  parent_folder_id?: string | null
+  revision: number
+  updated_at?: string
+}
+
+export interface ZergBoxFile {
+  id: string
+  name: string
+  folder_id?: string
+  mime_type?: string
+  size_bytes?: number
+  current_version?: number
+  content_sha256: string
+  revision: number
+  updated_at?: string
+}
+
+export interface ZergBoxFolderListing {
+  folder: ZergBoxFolder
+  folders: ZergBoxFolder[]
+  files: ZergBoxFile[]
+  breadcrumbs?: ZergBoxFolder[]
+}
+
+export interface ZergBoxMutationResult {
+  id?: string
+  folder?: ZergBoxFolder
+  file?: ZergBoxFile
+  version?: number
+}
+
+export type ZergBoxChangeKind = 'created' | 'content' | 'moved' | 'deleted' | 'restored'
+
+export interface ZergBoxContentChange {
+  cursor: number
+  entry_id: string
+  entry_kind: 'file' | 'folder'
+  change_kind: ZergBoxChangeKind
+  entry_name: string
+  parent_folder_id: string | null
+  previous_parent_folder_id: string | null
+  revision: number
+  content_sha256: string | null
+  created_at: string
+}
+
+export interface ZergBoxChangePage {
+  rootFolderId: string
+  changes: ZergBoxContentChange[]
+  nextCursor: number
+  hasMore: boolean
+}
+
+export interface ZergBoxByteUpload {
+  orgId: string
+  folderId: string
+  filename: string
+  bytes: Uint8Array
+  mediaType?: string
+  expectedAbsent?: true
+}
+
+export interface ZergBoxSyncClient {
+  getRootFolder(organizationId: string, options?: { limit?: number; offset?: number }): Promise<ZergBoxFolderListing>
+  getFolder(folderId: string, options?: { limit?: number; offset?: number }): Promise<ZergBoxFolderListing>
+  listChanges(rootFolderId: string, options?: { cursor?: number; limit?: number }): Promise<ZergBoxChangePage>
+  getChanges(input: { rootFolderId: string; cursor?: number; limit?: number }): Promise<ZergBoxChangePage>
+  createFolder(input: { orgId: string; parentFolderId: string; name: string; expectedAbsent?: true }): Promise<ZergBoxMutationResult>
+  updateFolder(input: { folderId: string; name?: string; parentFolderId?: string; expectedRevision: number }): Promise<ZergBoxMutationResult>
+  uploadBytes(input: ZergBoxByteUpload): Promise<ZergBoxMutationResult>
+  uploadFile(input: { orgId: string; folderId: string; filePath: string; filename?: string; replaceExisting?: boolean }): Promise<ZergBoxMutationResult>
+  updateFileBytes(input: { fileId: string; filename?: string; bytes: Uint8Array; mediaType?: string; expectedRevision: number }): Promise<ZergBoxMutationResult>
+  updateFileContent(input: { fileId: string; filePath: string; expectedRevision: number }): Promise<ZergBoxMutationResult>
+  updateFile(input: { fileId: string; name?: string; folderId?: string; expectedRevision: number }): Promise<ZergBoxMutationResult>
+  downloadFile(fileId: string, options?: { maxBytes?: number }): Promise<Uint8Array>
+  deleteRemoteFile(fileId: string, options: { expectedRevision: number }): Promise<unknown>
+  deleteRemoteFolder(folderId: string, options: { expectedRevision: number }): Promise<unknown>
+}
+
+export interface RemoteTree {
+  rootFolder: ZergBoxFolder
+  entries: SyncNode[]
+}
+
+export interface ZergBoxApiErrorDetails {
+  status?: number
+  body?: string
+}
+
+export interface ZergBoxSyncConflictDetails extends ZergBoxApiErrorDetails {
+  resourceType: 'file' | 'folder'
+  resourceId: string | null
+  resourcePath?: string
+  expectedRevision?: number
+  expectedAbsent?: true
+}
+
+export class ZergBoxApiError extends Error {
+  constructor(message: string, details?: ZergBoxApiErrorDetails)
+  status?: number
+  body?: string
+}
+
+export class ZergBoxSyncConflictError extends ZergBoxApiError {
+  constructor(message: string, details: ZergBoxSyncConflictDetails)
+  code: 'SYNC_CONFLICT'
+  recoverable: true
+  resourceType: 'file' | 'folder'
+  resourceId: string | null
+  resourcePath?: string
+  expectedRevision?: number
+  expectedAbsent?: true
+}
+
+export class ZergBoxClient implements ZergBoxSyncClient {
+  constructor(options: ZergBoxClientOptions)
+  listOrganizations(): Promise<ZergBoxOrganization[]>
+  getRootFolder(organizationId: string, options?: { limit?: number; offset?: number }): Promise<ZergBoxFolderListing>
+  getFolder(folderId: string, options?: { limit?: number; offset?: number }): Promise<ZergBoxFolderListing>
+  listChanges(rootFolderId: string, options?: { cursor?: number; limit?: number }): Promise<ZergBoxChangePage>
+  getChanges(input: { rootFolderId: string; cursor?: number; limit?: number }): Promise<ZergBoxChangePage>
+  createFolder(input: { orgId: string; parentFolderId: string; name: string; expectedAbsent?: true }): Promise<ZergBoxMutationResult>
+  updateFolder(input: { folderId: string; name?: string; parentFolderId?: string; expectedRevision: number }): Promise<ZergBoxMutationResult>
+  uploadBytes(input: ZergBoxByteUpload): Promise<ZergBoxMutationResult>
+  uploadFile(input: { orgId: string; folderId: string; filePath: string; filename?: string; replaceExisting?: boolean }): Promise<ZergBoxMutationResult>
+  updateFileBytes(input: { fileId: string; filename?: string; bytes: Uint8Array; mediaType?: string; expectedRevision: number }): Promise<ZergBoxMutationResult>
+  updateFileContent(input: { fileId: string; filePath: string; expectedRevision: number }): Promise<ZergBoxMutationResult>
+  updateFile(input: { fileId: string; name?: string; folderId?: string; expectedRevision: number }): Promise<ZergBoxMutationResult>
+  downloadFile(fileId: string, options?: { maxBytes?: number }): Promise<Uint8Array>
+  deleteRemoteFile(fileId: string, options: { expectedRevision: number }): Promise<unknown>
+  deleteRemoteFolder(folderId: string, options: { expectedRevision: number }): Promise<unknown>
+}
+
+export function fetchRemoteTree(
+  client: Pick<ZergBoxSyncClient, 'getRootFolder' | 'getFolder'>,
+  options: { orgId: string; rootFolderId?: string; pageSize?: number }
+): Promise<RemoteTree>
+
+export function remoteFileFingerprint(file: Partial<ZergBoxFile>): string

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@zergai/zergbox-client",
+  "version": "0.1.0",
+  "description": "Typed ZergBox API and bounded local sync client",
+  "type": "module",
+  "private": false,
+  "sideEffects": false,
+  "types": "./index.d.ts",
+  "packageManager": "npm@11.5.1",
+  "engines": {
+    "node": ">=22.19.0 <25",
+    "npm": ">=10.9.2 <12"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./sync": {
+      "types": "./sync.d.ts",
+      "import": "./dist/sync.js"
+    }
+  },
+  "files": [
+    "dist",
+    "index.d.ts",
+    "sync.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node ./scripts/build.mjs",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "esbuild": "0.27.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "license": "UNLICENSED",
+  "homepage": "https://zergbox.com",
+  "bugs": {
+    "url": "https://github.com/Epoch-ML/zerg/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Epoch-ML/zerg.git",
+    "directory": "zapps/zergbox/client"
+  },
+  "keywords": [
+    "zergbox",
+    "file-sync",
+    "knowledge-base"
+  ]
+}

package/sync.d.ts

@@ -0,0 +1,58 @@
+import type { SyncChange, ZergBoxSyncClient } from './index.js'
+
+export * from './index.js'
+
+export type TokenProvider = () => Promise<string | { token: string }> | string | { token: string }
+
+export interface CreateSyncSessionOptions {
+  client?: ZergBoxSyncClient
+  baseUrl?: string
+  tokenProvider?: TokenProvider
+  organizationId: string
+  rootFolderId: string
+  localRoot: string
+  statePath?: string
+  deviceId: string
+  intervalMs?: number
+  debounceMs?: number
+  requestTimeoutMs?: number
+  afterSync?: (result: SyncResult) => Promise<void> | void
+  onError?: (error: Error) => void
+}
+
+export interface SyncResult {
+  actions: SyncChange[]
+  localRoot: string
+  statePath: string
+  syncedAt: string | null
+  paused: boolean
+  locked: boolean
+}
+
+export interface SyncStatus {
+  state: string
+  paused: boolean
+  watching: boolean
+  closed: boolean
+  deviceId: string
+  organizationId: string
+  rootFolderId: string
+  localRoot: string
+  statePath: string
+  lastSyncedAt: string | null
+  actionCount: number | null
+  conflictCount: number | null
+  errorMessage: string | null
+}
+
+export interface SyncSession {
+  syncOnce(options?: { force?: boolean }): Promise<SyncResult>
+  watch(options?: { immediate?: boolean }): Promise<SyncStatus>
+  status(): Promise<SyncStatus>
+  pause(reason?: string): Promise<SyncStatus>
+  resume(): Promise<SyncStatus>
+  stopWatching(): Promise<SyncStatus>
+  close(): Promise<SyncStatus>
+}
+
+export function createSyncSession(options: CreateSyncSessionOptions): SyncSession