@indigoai-us/hq-cloud 5.46.0 → 5.47.0

package/src/vault-client.ts

@@ -181,6 +181,51 @@ export interface ExplicitGrant {
   source: GrantSource;
 }
 
+/** Presign operation: download / upload / delete. */
+export type PresignOp = "get" | "put" | "delete";
+
+/** One object's metadata as returned by GET /v1/files/list. */
+export interface VaultListedObject {
+  key: string;
+  size: number;
+  lastModified: string | null;
+  /**
+   * S3 ETag (quotes stripped) or null. Load-bearing for sync change-
+   * detection: the client stores it as remote-content identity and compares
+   * it to decide pull/skip/delete-safety — the same role `RemoteFile.etag`
+   * plays on the STS path. Mirrors the hq-pro `files/list` field (PR #269).
+   */
+  etag: string | null;
+  permission: GrantPermission;
+}
+
+/** One key in a batch presign request. */
+export interface PresignKeyInput {
+  key: string;
+  op?: PresignOp;
+  contentType?: string;
+  /** Custom object metadata to sign into a PUT (x-amz-meta-*). */
+  metadata?: Record<string, string>;
+}
+
+/** One result row from POST /v1/files/presign (per key, request order). */
+export interface PresignResultRow {
+  key: string;
+  op: PresignOp;
+  /** Present on success: the presigned URL. */
+  url?: string;
+  /**
+   * Present on a PUT success: the EXACT headers to send on the PUT so the
+   * SigV4 signature matches (Content-Type, SSE-KMS, every x-amz-meta-*).
+   */
+  headers?: Record<string, string>;
+  expiresIn?: number;
+  expiresAt?: string;
+  /** Present on per-key denial/validation failure. */
+  error?: string;
+  code?: string;
+}
+
 /**
  * Effective sync mode for a single membership. Mirrors the server's
  * resolved view from `GET /v1/memberships/{id}/sync-config`:
@@ -531,6 +576,62 @@ export class VaultClient {
     return data.grants ?? [];
   }
 
+  // -- Presigned-URL transport (vault list + presign) ----------------------
+
+  /**
+   * ACL-filtered list of objects under `prefix`. Backed by
+   * `GET /v1/files/list?company=&prefix=&cursor=`. Returns only the keys the
+   * caller can read, each with metadata (size, lastModified, permission), plus
+   * an opaque `cursor` for the next page (null when exhausted). Page the cursor
+   * until it is null.
+   */
+  async listFiles(
+    companyUid: string,
+    prefix?: string,
+    cursor?: string,
+  ): Promise<{
+    objects: VaultListedObject[];
+    cursor: string | null;
+    truncated: boolean;
+  }> {
+    const qs = new URLSearchParams({ company: companyUid });
+    if (prefix) qs.set("prefix", prefix);
+    if (cursor) qs.set("cursor", cursor);
+    const data = await this.get<{
+      objects?: VaultListedObject[];
+      cursor?: string | null;
+      truncated?: boolean;
+    }>(`/v1/files/list?${qs.toString()}`);
+    return {
+      objects: data.objects ?? [],
+      cursor: data.cursor ?? null,
+      truncated: data.truncated ?? false,
+    };
+  }
+
+  /**
+   * Batch-mint presigned get/put/delete URLs. Backed by
+   * `POST /v1/files/presign`. Authorization is PER KEY — denied/invalid keys
+   * come back as `results[i].error` (the call itself succeeds), so callers must
+   * inspect each row. PUT rows carry `headers` the client must replay verbatim.
+   */
+  async presign(input: {
+    companyUid: string;
+    op?: PresignOp;
+    expiresIn?: number;
+    keys: PresignKeyInput[];
+  }): Promise<{ results: PresignResultRow[]; expiresAt: string }> {
+    return this.post<{ results: PresignResultRow[]; expiresAt: string }>(
+      `/v1/files/presign`,
+      {
+        company: input.companyUid,
+        ...(input.op ? { op: input.op } : {}),
+        ...(input.expiresIn ? { expiresIn: input.expiresIn } : {}),
+        keys: input.keys,
+      },
+    );
+  }
+
   /**
    * Read the effective sync-mode for a single membership. Backed by
    * `GET /v1/memberships/{id}/sync-config` (hq-pro US-003).