{"_id":"@atzentis/storage-sdk","name":"@atzentis/storage-sdk","dist-tags":{"latest":"0.2.0"},"versions":{"0.2.0":{"name":"@atzentis/storage-sdk","version":"0.2.0","description":"Atzentis Storage SDK — TypeScript client for api.atzentis.cloud","keywords":["atzentis","storage","sdk","client","typescript"],"license":"MIT","author":{"name":"Atzentis","email":"dev@atzentis.com","url":"https://atzentis.com"},"homepage":"https://github.com/atzentis/atzentis-storage-sdk/tree/main/packages/core#readme","repository":{"type":"git","url":"git+https://github.com/atzentis/atzentis-storage-sdk.git","directory":"packages/core"},"type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"}},"sideEffects":false,"publishConfig":{"access":"public"},"peerDependencies":{"zod":"^3.23.0"},"peerDependenciesMeta":{"zod":{"optional":true}},"devDependencies":{"tsup":"^8.3.0","typescript":"^5.7.0","vitest":"^2.1.0","zod":"^3.23.0"},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest run","test:watch":"vitest","type-check":"tsc --noEmit"},"_id":"@atzentis/storage-sdk@0.2.0","bugs":{"url":"https://github.com/atzentis/atzentis-storage-sdk/issues"},"_integrity":"sha512-HKeBosr0JiBRlMzqkQtbAb2dYTnIhUxlX11GWUqXBzuqrkCfC5zdAIKTD7WT8L4BWEGYJONQpDyA4RQ+hyW1Hw==","_resolved":"/tmp/1a587b312f01d2fb8fdc92b6dbb2abee/atzentis-storage-sdk-0.2.0.tgz","_from":"file:atzentis-storage-sdk-0.2.0.tgz","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-HKeBosr0JiBRlMzqkQtbAb2dYTnIhUxlX11GWUqXBzuqrkCfC5zdAIKTD7WT8L4BWEGYJONQpDyA4RQ+hyW1Hw==","shasum":"c149771e7334b320a2cc59659d6102e3e38bd672","tarball":"https://registry.npmjs.org/@atzentis/storage-sdk/-/storage-sdk-0.2.0.tgz","fileCount":6,"unpackedSize":270193,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCENXPNyRv50xQno0elaJDFaaMHjfOHXGfUAPqLu26YUAIhAIRTDH4Cy6zrHkp20TVaQienJYGdKnu9QO734qivV4mM"}]},"_npmUser":{"name":"vassilibo","email":"vassilibo@outlook.com"},"directories":{},"maintainers":[{"name":"vassilibo","email":"vassilibo@outlook.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/storage-sdk_0.2.0_1781139275965_0.8044699328448897"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-11T00:54:35.797Z","0.2.0":"2026-06-11T00:54:36.095Z","modified":"2026-06-11T00:54:36.324Z"},"maintainers":[{"name":"vassilibo","email":"vassilibo@outlook.com"}],"description":"Atzentis Storage SDK — TypeScript client for api.atzentis.cloud","homepage":"https://github.com/atzentis/atzentis-storage-sdk/tree/main/packages/core#readme","keywords":["atzentis","storage","sdk","client","typescript"],"repository":{"type":"git","url":"git+https://github.com/atzentis/atzentis-storage-sdk.git","directory":"packages/core"},"author":{"name":"Atzentis","email":"dev@atzentis.com","url":"https://atzentis.com"},"bugs":{"url":"https://github.com/atzentis/atzentis-storage-sdk/issues"},"license":"MIT","readme":"# @atzentis/storage-sdk\n\nTypeScript client for the Atzentis Storage Cloud API (`api.atzentis.cloud`).\n\nThe core SDK ships a single `StorageClient` class that wraps the platform's\nHTTP surface with API key authentication, tenant injection, automatic retry\non transient failures, timeout enforcement, typed error classes, and cursor\npagination helpers. Domain services in later phases (`files`, `folders`,\n`search`, `annotations`, `processing`, `usage`) extend `BaseService` to share\nthis transport.\n\n## Installation\n\n```bash\npnpm add @atzentis/storage-sdk zod\n```\n\n`zod` is an optional peer dependency, used for runtime config validation.\n\n## Quick start\n\n```ts\nimport { StorageClient } from \"@atzentis/storage-sdk\";\n\nconst storage = new StorageClient({\n apiKey: process.env.ATZ_STORAGE_API_KEY!,\n tenantId: process.env.ATZ_TENANT_ID!,\n});\n\n// Upload a file\nconst file = await storage.files.upload(blob);\n\n// Search (hybrid)\nconst results = await storage.search.query({ q: \"quarterly report\" });\n\n// Annotate\nconst annotation = await storage.annotations.create({\n fileId: file.id,\n type: \"highlight\",\n position: { page: 1, x: 10, y: 20, width: 100, height: 30 },\n});\n\n// Run OCR and wait\nconst job = await storage.processing.ocr(file.id);\nconst completed = await job.completed();\n```\n\n## Domain services\n\n| Accessor | Surface |\n|---|---|\n| `client.files` | `upload`, `getUploadUrl`, `confirmUpload`, `getDownloadUrl`, `list`, `autoPaginate`, `get`, `update`, `delete` (single + batch) |\n| `client.folders` | `create`, `get`, `list`, `autoPaginate`, `update`, `move`, `delete`, `getTree` |\n| `client.search` | `query`, `fulltext`, `autoPaginateQuery`, `autoPaginateFulltext` |\n| `client.annotations` | `create`, `get`, `listByFile`, `autoPaginateByFile`, `update`, `delete`, `reply`, `listReplies`, `autoPaginateReplies`, `deleteReply` |\n| `client.processing` | `ocr`, `getOcrStatus`, `generateEmbedding`, `getEmbeddingStatus`, `generateThumbnail`, `getThumbnailStatus`, `getThumbnailUrl` — every enqueue returns `AwaitableJob` with a `completed()` poll helper |\n| `client.usage` | `getQuota`, `getUsage`, `getUsageHistory` |\n\n## Configuration\n\n| Option | Required | Default | Description |\n| -------------- | -------- | ----------------------------- | ------------------------------------------------------ |\n| `apiKey` | yes | — | API key — sent as `Authorization: Bearer {apiKey}` |\n| `tenantId` | yes | — | Tenant identifier — sent as `X-Tenant-ID: {tenantId}` |\n| `baseUrl` | no | `https://api.atzentis.cloud` | Override for sandbox / preview / self-hosted |\n| `timeoutMs` | no | `30000` | Per-request timeout (ms) |\n| `maxRetries` | no | `3` | Maximum retries on transient failures |\n| `retryDelayMs` | no | `200` | Initial backoff delay (ms) |\n| `fetch` | no | `globalThis.fetch` | Custom transport (e.g. `undici`, MSW, test mocks) |\n\nMissing `apiKey` or `tenantId` throws `StorageConfigError` synchronously.\n\n## Errors\n\nAll errors extend `BaseError` and carry `code` + `statusCode`:\n\n| Class | HTTP | Retryable |\n| ---------------------- | ---- | --------- |\n| `ValidationError` | 400 | no |\n| `AuthenticationError` | 401 | no |\n| `PermissionError` | 403 | no |\n| `NotFoundError` | 404 | no |\n| `ConflictError` | 409 | no |\n| `RateLimitError` | 429 | yes |\n| `ServerError` | 5xx | yes |\n| `ApiError` | other| no |\n| `NetworkError` | — | yes |\n| `TimeoutError` | — | yes |\n| `StorageConfigError` | — | no |\n\n`RateLimitError.retryAfter` honors the server's `Retry-After` header.\n\n## Retry behavior\n\n`maxRetries + 1` total attempts. Backoff is exponential with full jitter,\ncapped at 8s. Only retryable errors trigger another attempt; validation and\npermission errors fail fast.\n\n```ts\n// Disable retry for a single request\nawait storage.get(\"/files\", undefined, { retry: false });\n```\n\n## Cursor pagination\n\n```ts\nimport { paginate } from \"@atzentis/storage-sdk\";\n\nfor await (const file of paginate((p) => storage.get(\"/files\", p))) {\n console.log(file);\n}\n```\n\n`paginate` returns an `AsyncIterable` and stops when the server reports\n`hasNextPage: false`. Use `collectAll` for small result sets.\n\n## Extending: BaseService\n\n```ts\nimport { BaseService } from \"@atzentis/storage-sdk\";\nimport type { PaginatedResult } from \"@atzentis/storage-sdk\";\n\nclass FilesService extends BaseService {\n protected basePath = \"/files\";\n\n list(params?: { limit?: number }): Promise> {\n return this._list(params);\n }\n\n get(id: string): Promise {\n return this._get(this._buildPath(id));\n }\n}\n```\n\n## License\n\nMIT — © Atzentis\n","readmeFilename":"README.md","_rev":"1-9a6e9a80c25976502dc6ad44d22a48f6"}