@asgard-js/core 0.3.65 → 0.3.67

package/dist/lib/source-set-client.d.ts

@@ -0,0 +1,53 @@
+import { SourceSetClientConfig, SourceSetCopyMoveOptions, SourceSetCopyResult, SourceSetListAllOptions, SourceSetListAllResult, SourceSetListOptions, SourceSetListResult, SourceSetReadOptions, SourceSetReadResult, SourceSetStatResult, SourceSetWriteOptions, SourceSetWriteResult } from '../types/source-set-fs';
+
+/** The server rejects anything larger (`page_size` max 1000), so clamp rather than let it 400. */
+export declare const SOURCE_SET_MAX_PAGE_SIZE = 1000;
+/**
+ * Default ceiling for {@link AsgardSourceSetClient.listAll}.
+ *
+ * Ten pages of the maximum page size. Past this a file-tree node is not something anyone scrolls, and
+ * the walk is sequential, so the cost of going further is paid in round trips for entries nobody reads.
+ * It is a ceiling, not a silent truncation: the result reports `total` and `truncatedAtCap` so the UI
+ * can say how many were left out, and a caller who genuinely needs more raises `maxEntries`.
+ */
+export declare const SOURCE_SET_DEFAULT_MAX_ENTRIES = 10000;
+export default class AsgardSourceSetClient {
+    private readonly endpoint;
+    private readonly apiKey?;
+    private readonly customHeaders?;
+    constructor(config: SourceSetClientConfig);
+    /** Auth + caller headers for every request, including the multipart upload and the binary download. */
+    private headers;
+    /** Issue one volume request, turning any non-2xx into {@link HttpError} (409 included, see R8). */
+    private request;
+    /** One page of a directory (`GET volume/list?path=[&page&page_size]`). `path` may be the root `''`. */
+    list(path: string, options?: SourceSetListOptions): Promise<SourceSetListResult>;
+    /**
+     * F-026 — every entry in a directory, paging until `paging.total` or the cap.
+     *
+     * A failed page rejects rather than returning what it managed to collect: handing back half a
+     * directory that looks whole is the failure this exists to prevent.
+     */
+    listAll(path: string, options?: SourceSetListAllOptions): Promise<SourceSetListAllResult>;
+    /** Stat a path (`GET volume/stat?path=`). A missing path is 200 with `exists: false`, not a 404. */
+    stat(path: string): Promise<SourceSetStatResult>;
+    /** Read a file (`GET volume/file?path=[&offset_bytes&limit_bytes]`) as raw bytes. */
+    read(path: string, options?: SourceSetReadOptions): Promise<SourceSetReadResult>;
+    /**
+     * Write a file (`PUT volume/file?path=[&mode&create_only]`, `multipart/form-data` with a `file` field).
+     * With `createOnly`, an existing path is a 409 rather than an overwrite.
+     */
+    write(path: string, content: Blob | string, options?: SourceSetWriteOptions): Promise<SourceSetWriteResult>;
+    /** Create a directory and any missing parents (`POST volume/mkdir?path=`). */
+    mkdir(path: string): Promise<void>;
+    /** Delete a file or empty directory (`DELETE volume/item?path=`). */
+    remove(path: string): Promise<void>;
+    /** Recursively delete a directory (`DELETE volume/all?path=`). The volume root is not a valid target. */
+    removeAll(path: string): Promise<void>;
+    /** Copy a file or directory tree (`POST volume/copy?src=&dst=[&overwrite]`). */
+    copy(src: string, dst: string, options?: SourceSetCopyMoveOptions): Promise<SourceSetCopyResult>;
+    /** Move or rename (`POST volume/move?src=&dst=[&overwrite]`) — also how the UI renames. */
+    move(src: string, dst: string, options?: SourceSetCopyMoveOptions): Promise<void>;
+    private copyMoveQuery;
+}
+//# sourceMappingURL=source-set-client.d.ts.map

package/dist/lib/source-set-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-set-client.d.ts","sourceRoot":"","sources":["../../src/lib/source-set-client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,qBAAqB,EACrB,wBAAwB,EACxB,mBAAmB,EAEnB,uBAAuB,EACvB,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EAEnB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,wBAAwB,CAAC;AAehC,kGAAkG;AAClG,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C;;;;;;;GAOG;AACH,eAAO,MAAM,8BAA8B,QAAS,CAAC;AAcrD,MAAM,CAAC,OAAO,OAAO,qBAAqB;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAyB;gBAE5C,MAAM,EAAE,qBAAqB;IAMzC,uGAAuG;IACvG,OAAO,CAAC,OAAO;IASf,mGAAmG;YACrF,OAAO;IAarB,uGAAuG;IACjG,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAmBtF;;;;;OAKG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAqD/F,oGAAoG;IAC9F,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAetD,qFAAqF;IAC/E,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAiBtF;;;OAGG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAgBjH,8EAA8E;IACxE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC,qEAAqE;IAC/D,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzC,yGAAyG;IACnG,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5C,gFAAgF;IAC1E,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,wBAAwB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAStG,2FAA2F;IACrF,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvF,OAAO,CAAC,aAAa;CAMtB"}

package/dist/lib/source-set-client.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=source-set-client.spec.d.ts.map

package/dist/lib/source-set-client.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-set-client.spec.d.ts","sourceRoot":"","sources":["../../src/lib/source-set-client.spec.ts"],"names":[],"mappings":""}

package/dist/lib/source-set-path.d.ts

@@ -0,0 +1,13 @@
+/** The volume root. Only `list` / `listAll` accept it; every mutation needs a real path. */
+export declare const SOURCE_SET_VOLUME_ROOT = "";
+/**
+ * Validate a volume-relative path, returning it unchanged so it can be inlined into a query.
+ *
+ * @param path Volume-relative, e.g. `notes/todo.md`.
+ * @param options `allowRoot` permits the empty-string root — set it only for listing.
+ * @throws Error when the path has a leading or trailing slash, a doubled slash, or a `.` / `..` segment.
+ */
+export declare function assertVolumePath(path: string, options?: {
+    allowRoot?: boolean;
+}): string;
+//# sourceMappingURL=source-set-path.d.ts.map

package/dist/lib/source-set-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-set-path.d.ts","sourceRoot":"","sources":["../../src/lib/source-set-path.ts"],"names":[],"mappings":"AAOA,4FAA4F;AAC5F,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAKzC;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAwBxF"}

package/dist/lib/source-set-path.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=source-set-path.spec.d.ts.map

package/dist/lib/source-set-path.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-set-path.spec.d.ts","sourceRoot":"","sources":["../../src/lib/source-set-path.spec.ts"],"names":[],"mappings":""}

package/dist/types/index.d.ts

@@ -7,6 +7,7 @@ export type * from './subagent';
 export type * from './event-emitter';
 export type * from './blob';
 export type * from './sandbox-fs';
+export type * from './source-set-fs';
 export { HttpError, isHttpError } from './http-error';
 export { ChannelBusyError, isChannelBusyError } from './channel-busy-error';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,QAAQ,CAAC;AAC5B,mBAAmB,UAAU,CAAC;AAC9B,mBAAmB,WAAW,CAAC;AAC/B,mBAAmB,gBAAgB,CAAC;AACpC,mBAAmB,QAAQ,CAAC;AAC5B,mBAAmB,YAAY,CAAC;AAChC,mBAAmB,iBAAiB,CAAC;AACrC,mBAAmB,QAAQ,CAAC;AAC5B,mBAAmB,cAAc,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,QAAQ,CAAC;AAC5B,mBAAmB,UAAU,CAAC;AAC9B,mBAAmB,WAAW,CAAC;AAC/B,mBAAmB,gBAAgB,CAAC;AACpC,mBAAmB,QAAQ,CAAC;AAC5B,mBAAmB,YAAY,CAAC;AAChC,mBAAmB,iBAAiB,CAAC;AACrC,mBAAmB,QAAQ,CAAC;AAC5B,mBAAmB,cAAc,CAAC;AAClC,mBAAmB,iBAAiB,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/types/source-set-fs.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Everything the client needs. `sourceSetEndpoint` points at `…/volume` directly, mirroring how
+ * `botProviderEndpoint` is passed whole rather than assembled from parts.
+ */
+export interface SourceSetClientConfig {
+    /**
+     * The volume endpoint, e.g. `{EDGE}/ns/{ns}/source-set/{name}/volume` or a BFF relay such as
+     * `{PLATFORM_API}/v1/source-set/{id}/volume`. A trailing slash is tolerated.
+     */
+    sourceSetEndpoint: string;
+    /**
+     * Sent as `X-API-KEY`. Omit when the endpoint is a BFF relay — the relay holds the volume key, and
+     * it should never reach the browser.
+     */
+    apiKey?: string;
+    /** Merged into every request, e.g. `{ Authorization: 'Bearer …' }` for a BFF relay. */
+    customHeaders?: Record<string, string>;
+}
+/** One directory entry from `GET volume/list`. */
+export interface SourceSetDirEntry {
+    /** Basename only — the backend sends no path prefix; absolute paths are the caller's to assemble. */
+    name: string;
+    isDir: boolean;
+    /** File size in bytes (0 for directories). */
+    sizeBytes: number;
+    /** Modification time, unix seconds. */
+    mtimeUnix: number;
+    /** Unix file mode (e.g. 420 = 0644). */
+    mode: number;
+}
+/** Pagination cursor returned alongside a listing. Real paging — there is no `truncated` here. */
+export interface SourceSetPaging {
+    /** 0-based page index. */
+    index: number;
+    /** Entries per page. */
+    size: number;
+    /** Total entries in the directory across all pages. */
+    total: number;
+}
+/** Query options for `GET volume/list`. */
+export interface SourceSetListOptions {
+    /** 0-based page index; defaults to 0 server-side. */
+    page?: number;
+    /** Entries per page. Clamped to the server maximum of 1000. */
+    pageSize?: number;
+}
+/** `GET volume/list` result. */
+export interface SourceSetListResult {
+    entries: SourceSetDirEntry[];
+    /**
+     * `null` when the response carried no paging at either layer.
+     *
+     * Deliberately not synthesized from `entries.length`: a made-up total is indistinguishable from a
+     * real one, and {@link AsgardSourceSetClient.listAll} would read it as "that was the whole
+     * directory" — the silent truncation F-026 exists to prevent.
+     */
+    paging: SourceSetPaging | null;
+}
+/** Options for the auto-paging walk (F-026). */
+export interface SourceSetListAllOptions {
+    /** Per-request page size; clamped to the server maximum of 1000. */
+    pageSize?: number;
+    /** Stop after this many entries. Defaults to `SOURCE_SET_DEFAULT_MAX_ENTRIES`. */
+    maxEntries?: number;
+}
+/** Result of the auto-paging walk (F-026). */
+export interface SourceSetListAllResult {
+    entries: SourceSetDirEntry[];
+    /**
+     * What the backend says the directory holds, or **0 when it never said**. Compare against
+     * `entries.length` for the shortfall; a 0 here with `complete: false` means the shortfall exists but
+     * its size is unknown.
+     */
+    total: number;
+    /**
+     * False when `entries` is either known not to be the whole directory, or cannot be shown to be.
+     *
+     * Three things set it false, and the caller cannot tell them apart on purpose — all three mean the
+     * same thing to a user: the cap stopped the walk; the backend sent no paging and a full page, so
+     * "is there more?" is unanswerable; or a page came back indexed differently from the one requested,
+     * which makes every further page untrustworthy.
+     */
+    complete: boolean;
+}
+/** Optional byte range for `GET volume/file`. */
+export interface SourceSetReadOptions {
+    offsetBytes?: number;
+    limitBytes?: number;
+}
+/** `GET volume/file` result: raw bytes plus the `X-Total-Bytes` / `X-Truncated` headers. */
+export interface SourceSetReadResult {
+    content: Blob;
+    /** Full file size in bytes (`X-Total-Bytes`), independent of any range limit. */
+    totalBytes: number;
+    /**
+     * `X-Truncated` — whether content remains **past** what was returned. Reading to EOF with only an
+     * offset is therefore not a truncation.
+     */
+    truncated: boolean;
+}
+/** Options for `PUT volume/file`. */
+export interface SourceSetWriteOptions {
+    /** Unix file mode in decimal (default 420 = 0644). */
+    mode?: number;
+    /** Fail with 409 instead of overwriting when the path already exists. */
+    createOnly?: boolean;
+}
+/** `PUT volume/file` result. */
+export interface SourceSetWriteResult {
+    bytesWritten: number;
+}
+/** `GET volume/stat` result. A missing path is 200 with `exists: false`, not a 404. */
+export interface SourceSetStatResult {
+    exists: boolean;
+    isDir: boolean;
+    sizeBytes: number;
+    mtimeUnix: number;
+    mode: number;
+    etag?: string;
+}
+/** Options for `POST volume/copy` and `POST volume/move`. */
+export interface SourceSetCopyMoveOptions {
+    /** Replace an existing destination; without it an occupied destination is a 409. */
+    overwrite?: boolean;
+}
+/** `POST volume/copy` result. */
+export interface SourceSetCopyResult {
+    bytesCopied: number;
+}
+//# sourceMappingURL=source-set-fs.d.ts.map

package/dist/types/source-set-fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-set-fs.d.ts","sourceRoot":"","sources":["../../src/types/source-set-fs.ts"],"names":[],"mappings":"AASA;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uFAAuF;IACvF,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxC;AAED,kDAAkD;AAClD,MAAM,WAAW,iBAAiB;IAChC,qGAAqG;IACrG,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,kGAAkG;AAClG,MAAM,WAAW,eAAe;IAC9B,0BAA0B;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,2CAA2C;AAC3C,MAAM,WAAW,oBAAoB;IACnC,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,gCAAgC;AAChC,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B;;;;;;OAMG;IACH,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC;CAChC;AAED,gDAAgD;AAChD,MAAM,WAAW,uBAAuB;IACtC,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,8CAA8C;AAC9C,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;OAOG;IACH,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,iDAAiD;AACjD,MAAM,WAAW,oBAAoB;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,4FAA4F;AAC5F,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,IAAI,CAAC;IACd,iFAAiF;IACjF,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,qCAAqC;AACrC,MAAM,WAAW,qBAAqB;IACpC,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,gCAAgC;AAChC,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,uFAAuF;AACvF,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,6DAA6D;AAC7D,MAAM,WAAW,wBAAwB;IACvC,oFAAoF;IACpF,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,iCAAiC;AACjC,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;CACrB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asgard-js/core",
-  "version": "0.3.65",
+  "version": "0.3.67",
   "dependencies": {
     "@microsoft/fetch-event-source": "^2.0.1",
     "rxjs": "^7.8.1",