@ariestools/datalake-cli 0.3.0 → 0.3.1

package/README.md

@@ -15,3 +15,27 @@ import { createDatalakeClient, ExactRootArchive, startRetainedDatalake } from '@
 ```
 
 `startRetainedDatalake` forks `retainedDatalakeWorker.mjs` from beside the library. The worker bundles the private control and plane, so installing this package needs no private or restricted package.
+
+Its type declarations are the facade's own: self-contained, with payloads typed as JSON values and the payload client taking and returning `unknown`, so code written against `@ariestools/cli/datalake` compiles once its import path changes.
+
+### Retained local datalake
+
+`startRetainedDatalake` starts a datalake for disposable local
+qualification. It owns an isolated loopback worker and returns `url`, `restart()`
+and `stop()`. Supply an absolute `directory` and, for a new corpus, a
+`DatalakeDescriptor`. The directory holds public descriptor/payload data only;
+the signing secret is ephemeral. Restart retains the endpoint and refuses to
+recreate a missing descriptor or overwrite a conflicting descriptor. A successful
+stop means the owned child and its pipes have closed. Readiness and stop deadlines
+are configurable positive integers up to 60 seconds.
+
+Optional `initialPayloads` seed at most 4096 public bodies and 16 MiB into a newly
+created descriptor. They are never replayed during restart; trying to seed an
+existing descriptor fails. This is a local fixture facility, not a managed
+production service or an account recovery journal.
+
+The same export provides `ExactRootArchive` and its self-contained types.
+It requires a trusted native-root `identify` callback, explicit resource limits,
+and an append-only token supplier. Reads are anonymous and verify original roots.
+A matching hash establishes integrity; the consuming protocol decides authority
+and admissibility. No private control/plane dependency is needed downstream.

package/dist/node/index.d.ts

@@ -1,19 +1,346 @@
-/**
- * The programmatic datalake surface of `@ariestools/datalake-cli`, which
- * replaces `@ariestools/cli/datalake`: the public client and core APIs, the
- * local dev-server inspection, and a retained local datalake for fixtures.
- * The client and core are public dependencies; the retained datalake's worker
- * bundles the private control and plane, so consumers install no private
- * package.
- */
-export type { RetainedDatalake, RetainedDatalakeOptions } from './retainedDatalake.ts';
-export { startRetainedDatalake } from './retainedDatalake.ts';
-export type { CreateDatalakeClientOptions } from '@ariestools/aries-datalake-client';
-export type { AuthTokenSource, DatalakeClient, PayloadsAuthTokenSource, PayloadsClient, RestDatalakeClientOptions, RestPayloadsClientOptions, StoredCredentials, WalletJwtCredentials, } from '@ariestools/aries-datalake-client';
-export type { ExactRootArchiveBody, ExactRootArchiveCallOptions, ExactRootArchiveErrorCode, ExactRootArchiveLimits, ExactRootArchiveOptions, ExactRootArchiveRoot, ExactRootArchiveTokenRequest, ExactRootArchiveWriteState, } from '@ariestools/aries-datalake-client';
-export { clearCredentials, clearDefaultDatalake, createDatalakeClient, getCredentialsLocation, getDefaultDatalake, loadCredentials, LocalDatalakeClient, RestDatalakeClient, RestPayloadsClient, saveCredentials, setDefaultDatalake, } from '@ariestools/aries-datalake-client';
-export { ExactRootArchive, ExactRootArchiveError } from '@ariestools/aries-datalake-client';
-export type { DatalakeDevServerEndpointReport, DatalakeDevServerExitCode, DatalakeDevServerReport, DatalakeDevServerStatus, InspectDatalakeDevServerOptions, } from '@ariestools/aries-datalake-client/dev';
-export { inspectDatalakeDevServer } from '@ariestools/aries-datalake-client/dev';
-export type { DatalakeDescriptor, Payload } from '@ariestools/aries-datalake-core';
-//# sourceMappingURL=index.d.ts.map
+/** Programmatic datalake client API of @ariestools/datalake-cli, self-contained: it names no other package's types. */
+
+export interface AuthTokenRequest {
+  audience: string
+}
+export type AuthTokenSupplier = (request: AuthTokenRequest) => Promise<string>
+export type AuthTokenSource = string | AuthTokenSupplier
+export type PayloadsAuthTokenSource = AuthTokenSource
+
+export type DatalakeRole = 'viewer' | 'runner'
+export type DatalakePrincipal = string
+export type DatalakeTier = 'small' | 'medium' | 'large' | 'archive'
+export type DatalakeRegion = 'us-west-2' | 'us-east-1' | 'eu-west-1'
+export type DatalakeStatus =
+  | 'pending'
+  | 'provisioning'
+  | 'ready'
+  | 'resizing'
+  | 'deprovisioning'
+  | 'deleted'
+  | 'error'
+
+export interface RateLimitOverrides {
+  anonymousPerMinute?: number
+  authenticatedPerMinute?: number
+  burstFactor?: number
+}
+
+export interface DatalakeConfig {
+  allowedSchemas?: string[]
+  disallowedSchemas?: string[]
+  iops?: number
+  rateLimits?: RateLimitOverrides
+  region?: DatalakeRegion
+  retentionDays?: number | null
+  sizeBytes?: number
+  tier: DatalakeTier
+  /** @deprecated No-op; archivist recomputes hashes trustlessly. */
+  verifyHashes?: boolean
+}
+
+export interface AclEntry {
+  grantedAt: string
+  grantedBy?: string
+  principal: DatalakePrincipal
+  role: DatalakeRole
+}
+
+export interface DatalakeUsage {
+  bytesStored: number
+  bytesStoredLimit: number
+  payloadCount: number
+  readsLast24h: number
+  writesLast24h: number
+}
+
+export interface DatalakeDescriptor {
+  acl: AclEntry[]
+  config: DatalakeConfig
+  createdAt: string
+  errorMessage?: string
+  id: string
+  name: string
+  ownerId: string
+  status: DatalakeStatus
+  updatedAt: string
+  url?: string
+  usage?: DatalakeUsage
+}
+
+export interface DatalakeToken {
+  datalakeId: string
+  expiresAt: string
+  role: DatalakeRole
+  token: string
+  url: string
+}
+
+export interface CreateDatalakeRequest {
+  config: DatalakeConfig
+  name: string
+}
+
+export interface GrantRequest {
+  datalakeId: string
+  principal: DatalakePrincipal
+  role: DatalakeRole
+}
+
+export interface RevokeRequest {
+  datalakeId: string
+  principal: DatalakePrincipal
+}
+
+export interface TokenRequest {
+  datalakeId: string
+  role: DatalakeRole
+  ttlSeconds?: number
+}
+
+export interface WalletJwtCredentials {
+  controlAudience?: string
+  offset?: string
+  ttlSeconds?: number
+}
+
+export interface StoredCredentials {
+  authToken?: string
+  baseUrl: string
+  expiresAt?: string
+  refreshToken?: string
+  userId?: string
+  walletJwt?: WalletJwtCredentials
+}
+
+export interface CreateDatalakeClientOptions {
+  authToken?: AuthTokenSource
+  baseUrl?: string
+  driver?: 'local' | 'rest'
+}
+
+export interface RestDatalakeClientOptions {
+  authToken: AuthTokenSource
+  audience?: string
+  baseUrl: string
+  fetchImpl?: typeof fetch
+}
+
+export interface RestPayloadsClientOptions {
+  authToken: PayloadsAuthTokenSource
+  baseUrl: string
+  datalakeId: string
+  fetchImpl?: typeof fetch
+}
+
+export interface DatalakeInsertSummary {
+  duplicates: number
+  rejected: string[]
+}
+
+/** Result of PayloadsClient.insert — matches RestPayloadsClient runtime. */
+export interface InsertPayloadsResult {
+  inserted: unknown[]
+  summary: DatalakeInsertSummary
+}
+
+export interface NextPayloadsResult {
+  nextCursor?: string
+  payloads: unknown[]
+}
+
+export interface DatalakeUsageReport {
+  datalakeId: string
+  payloadCount: number
+  rateLimits?: {
+    anonymous?: { limit: number; remaining: number }
+    authenticated?: { limit: number; remaining: number }
+  }
+}
+
+export type DatalakeDevServerStatus =
+  | 'healthy'
+  | 'degraded'
+  | 'unresponsive'
+  | 'stale'
+  | 'stopped'
+
+export type DatalakeDevServerExitCode = 0 | 2 | 3
+
+export interface DatalakeDevServerEndpointReport {
+  healthy: boolean
+  url: string
+}
+
+export interface DatalakeDevServerReport {
+  schemaVersion: 1
+  status: DatalakeDevServerStatus
+  exitCode: DatalakeDevServerExitCode
+  process: {
+    running: boolean
+    pid: number | null
+    startedAt: string | null
+  }
+  endpoints: {
+    control: DatalakeDevServerEndpointReport | null
+    plane: DatalakeDevServerEndpointReport | null
+  }
+}
+
+export interface InspectDatalakeDevServerOptions {
+  timeoutMs?: number
+}
+
+export interface PayloadsClient {
+  clear(): Promise<{ removed: number }>
+  delete(hash: string): Promise<void>
+  get(hash: string): Promise<unknown>
+  getMany(hashes: string[]): Promise<unknown[]>
+  insert(payloads: unknown[]): Promise<InsertPayloadsResult>
+  next(options?: {
+    cursor?: string
+    limit?: number
+    order?: 'asc' | 'desc'
+    schemas?: string[]
+  }): Promise<NextPayloadsResult>
+  usage(): Promise<DatalakeUsageReport>
+}
+
+export interface DatalakeClient {
+  create(request: CreateDatalakeRequest): Promise<DatalakeDescriptor>
+  describe(idOrName: string): Promise<DatalakeDescriptor>
+  destroy(idOrName: string): Promise<void>
+  grant(request: GrantRequest): Promise<DatalakeDescriptor>
+  list(): Promise<DatalakeDescriptor[]>
+  mintToken(request: TokenRequest): Promise<DatalakeToken>
+  revoke(request: RevokeRequest): Promise<DatalakeDescriptor>
+}
+
+export declare function createDatalakeClient(options?: CreateDatalakeClientOptions): DatalakeClient
+export declare function inspectDatalakeDevServer(
+  options?: InspectDatalakeDevServerOptions,
+): Promise<DatalakeDevServerReport>
+export declare class LocalDatalakeClient implements DatalakeClient {
+  create(request: CreateDatalakeRequest): Promise<DatalakeDescriptor>
+  describe(idOrName: string): Promise<DatalakeDescriptor>
+  destroy(idOrName: string): Promise<void>
+  grant(request: GrantRequest): Promise<DatalakeDescriptor>
+  list(): Promise<DatalakeDescriptor[]>
+  mintToken(request: TokenRequest): Promise<DatalakeToken>
+  revoke(request: RevokeRequest): Promise<DatalakeDescriptor>
+}
+export declare class RestDatalakeClient implements DatalakeClient {
+  constructor(options: RestDatalakeClientOptions)
+  create(request: CreateDatalakeRequest): Promise<DatalakeDescriptor>
+  describe(idOrName: string): Promise<DatalakeDescriptor>
+  destroy(idOrName: string): Promise<void>
+  grant(request: GrantRequest): Promise<DatalakeDescriptor>
+  list(): Promise<DatalakeDescriptor[]>
+  mintToken(request: TokenRequest): Promise<DatalakeToken>
+  revoke(request: RevokeRequest): Promise<DatalakeDescriptor>
+}
+export declare class RestPayloadsClient implements PayloadsClient {
+  constructor(options: RestPayloadsClientOptions)
+  clear(): Promise<{ removed: number }>
+  delete(hash: string): Promise<void>
+  get(hash: string): Promise<unknown>
+  getMany(hashes: string[]): Promise<unknown[]>
+  insert(payloads: unknown[]): Promise<InsertPayloadsResult>
+  next(options?: {
+    cursor?: string
+    limit?: number
+    order?: 'asc' | 'desc'
+    schemas?: string[]
+  }): Promise<NextPayloadsResult>
+  usage(): Promise<DatalakeUsageReport>
+}
+
+export declare function loadCredentials(): StoredCredentials | undefined
+export declare function saveCredentials(credentials: StoredCredentials): void
+export declare function clearCredentials(): void
+export declare function getCredentialsLocation(): string
+export declare function getDefaultDatalake(): string | undefined
+export declare function setDefaultDatalake(name: string, id?: string): void
+export declare function clearDefaultDatalake(): void
+export type JsonPrimitive = boolean | null | number | string
+export type JsonValue = JsonPrimitive | JsonObject | JsonValue[]
+export interface JsonObject { [key: string]: JsonValue }
+export interface Payload { schema: string; $sources?: string[]; [key: string]: JsonValue | undefined }
+
+export interface ExactRootArchiveLimits {
+  readonly maxConcurrentOperations: number
+  readonly maxOperationMilliseconds: number
+  readonly maxRequestBytes: number
+  readonly maxResponseBytes: number
+  readonly maxRoots: number
+  readonly maxTokenBytes: number
+}
+
+export interface ExactRootArchiveTokenRequest {
+  readonly audience: string
+  readonly scope: 'payload:append'
+  readonly signal: AbortSignal
+}
+
+export interface ExactRootArchiveOptions {
+  /** Absolute, credential-free configured plane URL. */
+  readonly baseUrl: string
+  readonly datalakeId: string
+  /** Trusted transport preserving signal, no redirects and credential policy. */
+  readonly fetchImpl?: typeof fetch
+  /** Explicit domain of the native SDK identity callback, not a JSON digest. */
+  readonly hashDomain: string
+  /** Trusted owning SDK algorithm; preserve client metadata and ignore only SDK storage metadata. */
+  readonly identify: (this: void, payload: Payload) => Promise<string>
+  readonly limits: ExactRootArchiveLimits
+  /** Trusted private issuer adapter, invoked only for append on this lake. */
+  readonly tokenSupplier: (this: void, request: ExactRootArchiveTokenRequest) => Promise<string>
+}
+
+export interface ExactRootArchiveBody {
+  readonly hashDomain: string
+  readonly payload: Payload
+  readonly root: string
+}
+
+export interface ExactRootArchiveRoot {
+  readonly hashDomain: string
+  readonly root: string
+}
+
+export interface ExactRootArchiveCallOptions {
+  readonly signal?: AbortSignal
+}
+
+export type ExactRootArchiveErrorCode = 'invalid-request' | 'unsupported-domain' | 'capacity' | 'cancelled'
+  | 'deadline' | 'token' | 'transport' | 'resource' | 'private' | 'missing' | 'altered' | 'invalid-response'
+export type ExactRootArchiveWriteState = 'not-started' | 'uncertain' | 'acknowledged'
+
+
+export declare class ExactRootArchiveError extends Error {
+  readonly code: ExactRootArchiveErrorCode
+  readonly writeState: ExactRootArchiveWriteState
+  constructor(code: ExactRootArchiveErrorCode, writeState?: ExactRootArchiveWriteState)
+}
+export declare class ExactRootArchive {
+  readonly hashDomain: string
+  readonly limits: ExactRootArchiveLimits
+  constructor(options: ExactRootArchiveOptions)
+  get outstandingOperations(): number
+  read(roots: readonly ExactRootArchiveRoot[], options?: ExactRootArchiveCallOptions): Promise<ExactRootArchiveBody[]>
+  write(bodies: readonly ExactRootArchiveBody[], options?: ExactRootArchiveCallOptions): Promise<ExactRootArchiveBody[]>
+}
+export interface RetainedDatalakeOptions {
+  readonly descriptor?: DatalakeDescriptor
+  readonly directory: string
+  readonly initialPayloads?: readonly Payload[]
+  readonly readinessTimeoutMilliseconds?: number
+  readonly stopTimeoutMilliseconds?: number
+}
+export interface RetainedDatalake {
+  readonly url: string
+  restart(): Promise<void>
+  stop(): Promise<void>
+}
+export declare function startRetainedDatalake(options: RetainedDatalakeOptions): Promise<RetainedDatalake>
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ariestools/datalake-cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "The datalake CLI that aries and ariesi spawn, and the programmatic datalake client surface",
   "keywords": [
     "ariestools",
@@ -41,8 +41,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@ariestools/aries-datalake-client": "~0.3.0",
-    "@ariestools/aries-datalake-core": "~0.3.0",
+    "@ariestools/aries-datalake-client": "~0.3.1",
+    "@ariestools/aries-datalake-core": "~0.3.1",
     "@ariestools/cli-kit": "~2.1.0",
     "@ariestools/cli-kit-daemon": "~2.1.0",
     "@ariestools/cli-kit-node": "~2.1.0",
@@ -57,8 +57,8 @@
   "devDependencies": {
     "@ariestools/actor-model": "~2.0.0",
     "@ariestools/actor-system": "~2.0.0",
-    "@ariestools/aries-datalake-control": "~0.3.0",
-    "@ariestools/aries-datalake-plane": "~0.3.0",
+    "@ariestools/aries-datalake-control": "~0.3.1",
+    "@ariestools/aries-datalake-plane": "~0.3.1",
     "@ariestools/eslint-config-flat": "~10.2.1",
     "@ariestools/sdk": "~9.0.2",
     "@ariestools/toolchain": "~10.2.1",
@@ -86,6 +86,6 @@
   },
   "scripts": {
     "aries-datalake": "node dist/node/bin/datalake.mjs",
-    "package-compile": "tsc -p tsconfig.build.json --noEmit && package-compile-only && rolldown -c rolldown.config.ts && node scripts/embedDaemon.mjs"
+    "package-compile": "tsc -p tsconfig.build.json --noEmit && package-compile-only && rolldown -c rolldown.config.ts && node scripts/embedDaemon.mjs && node scripts/emitLibraryTypes.mjs"
   }
 }

package/dist/node/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,YAAY,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAA;AACtF,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAC7D,YAAY,EAAE,2BAA2B,EAAE,MAAM,mCAAmC,CAAA;AACpF,YAAY,EACV,eAAe,EACf,cAAc,EACd,uBAAuB,EACvB,cAAc,EACd,yBAAyB,EACzB,yBAAyB,EACzB,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,mCAAmC,CAAA;AAC1C,YAAY,EACV,oBAAoB,EAAE,2BAA2B,EAAE,yBAAyB,EAC5E,sBAAsB,EAAE,uBAAuB,EAAE,oBAAoB,EACrE,4BAA4B,EAAE,0BAA0B,GACzD,MAAM,mCAAmC,CAAA;AAC1C,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,kBAAkB,EAClB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,EACf,kBAAkB,GACnB,MAAM,mCAAmC,CAAA;AAC1C,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAA;AAC3F,YAAY,EACV,+BAA+B,EAC/B,yBAAyB,EACzB,uBAAuB,EACvB,uBAAuB,EACvB,+BAA+B,GAChC,MAAM,uCAAuC,CAAA;AAC9C,OAAO,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAA;AAChF,YAAY,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAA"}