hazo_files 1.6.0 → 2.0.1

package/dist/testing/index.d.mts

@@ -0,0 +1,62 @@
+import { Readable } from 'node:stream';
+
+type StoragePath = string;
+interface PutOpts {
+    /** Reject if the target path already exists (atomic). */
+    ifNotExists?: boolean;
+    /** Hint for content-type; provider may sniff if absent. */
+    contentType?: string;
+    /** Free-form key/value metadata persisted with the file when supported. */
+    metadata?: Record<string, string>;
+}
+interface PutResult {
+    /** Provider tag — `"app_file_server"`, `"gdrive"`, `"in_memory"`. */
+    provider: string;
+    /** Provider-native identifier (path for app-server; file ID for GDrive). */
+    native_id: string;
+    /** Size in bytes of the persisted body. */
+    size: number;
+}
+interface SignedUrlOpts {
+    /** Seconds the URL is valid for. */
+    ttl_seconds?: number;
+    /** Suggested download filename (Content-Disposition). */
+    filename_hint?: string;
+}
+interface ProbeResult {
+    ok: boolean;
+    /** Machine-readable error tag when ok=false. */
+    error?: "drive_not_shared" | "write_denied" | "invalid_id" | "transient" | "config_missing";
+    /** Free-form detail for logging. */
+    message?: string;
+}
+/**
+ * Storage provider abstraction. Every method MUST be idempotent at the
+ * data-content level — re-invoking put with identical body is allowed.
+ *
+ * Paths are logical; providers translate to native identifiers internally.
+ */
+interface FileStorageProvider {
+    put(path: StoragePath, body: Buffer | Readable, opts?: PutOpts): Promise<PutResult>;
+    get(path: StoragePath): Promise<Buffer | Readable>;
+    delete(path: StoragePath): Promise<void>;
+    exists(path: StoragePath): Promise<boolean>;
+    getSignedUrl(path: StoragePath, opts?: SignedUrlOpts): Promise<string>;
+    /** Used by validation cron + onboarding step 2. */
+    probe(): Promise<ProbeResult>;
+}
+
+declare class InMemoryProvider implements FileStorageProvider {
+    readonly provider_tag: "in_memory";
+    private readonly store;
+    put(path: string, body: Buffer | Readable, opts?: PutOpts): Promise<PutResult>;
+    get(path: string): Promise<Buffer>;
+    delete(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    getSignedUrl(path: string, _opts?: SignedUrlOpts): Promise<string>;
+    probe(): Promise<ProbeResult>;
+    /** Test-only escape hatch — exposes the internal store for assertions. */
+    snapshot(): Map<string, Buffer>;
+}
+
+export { InMemoryProvider };

package/dist/testing/index.d.ts

@@ -0,0 +1,62 @@
+import { Readable } from 'node:stream';
+
+type StoragePath = string;
+interface PutOpts {
+    /** Reject if the target path already exists (atomic). */
+    ifNotExists?: boolean;
+    /** Hint for content-type; provider may sniff if absent. */
+    contentType?: string;
+    /** Free-form key/value metadata persisted with the file when supported. */
+    metadata?: Record<string, string>;
+}
+interface PutResult {
+    /** Provider tag — `"app_file_server"`, `"gdrive"`, `"in_memory"`. */
+    provider: string;
+    /** Provider-native identifier (path for app-server; file ID for GDrive). */
+    native_id: string;
+    /** Size in bytes of the persisted body. */
+    size: number;
+}
+interface SignedUrlOpts {
+    /** Seconds the URL is valid for. */
+    ttl_seconds?: number;
+    /** Suggested download filename (Content-Disposition). */
+    filename_hint?: string;
+}
+interface ProbeResult {
+    ok: boolean;
+    /** Machine-readable error tag when ok=false. */
+    error?: "drive_not_shared" | "write_denied" | "invalid_id" | "transient" | "config_missing";
+    /** Free-form detail for logging. */
+    message?: string;
+}
+/**
+ * Storage provider abstraction. Every method MUST be idempotent at the
+ * data-content level — re-invoking put with identical body is allowed.
+ *
+ * Paths are logical; providers translate to native identifiers internally.
+ */
+interface FileStorageProvider {
+    put(path: StoragePath, body: Buffer | Readable, opts?: PutOpts): Promise<PutResult>;
+    get(path: StoragePath): Promise<Buffer | Readable>;
+    delete(path: StoragePath): Promise<void>;
+    exists(path: StoragePath): Promise<boolean>;
+    getSignedUrl(path: StoragePath, opts?: SignedUrlOpts): Promise<string>;
+    /** Used by validation cron + onboarding step 2. */
+    probe(): Promise<ProbeResult>;
+}
+
+declare class InMemoryProvider implements FileStorageProvider {
+    readonly provider_tag: "in_memory";
+    private readonly store;
+    put(path: string, body: Buffer | Readable, opts?: PutOpts): Promise<PutResult>;
+    get(path: string): Promise<Buffer>;
+    delete(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    getSignedUrl(path: string, _opts?: SignedUrlOpts): Promise<string>;
+    probe(): Promise<ProbeResult>;
+    /** Test-only escape hatch — exposes the internal store for assertions. */
+    snapshot(): Map<string, Buffer>;
+}
+
+export { InMemoryProvider };

package/dist/testing/index.js

@@ -0,0 +1,71 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/testing/index.ts
+var index_exports = {};
+__export(index_exports, {
+  InMemoryProvider: () => InMemoryProvider
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/providers/in-memory.ts
+var InMemoryProvider = class {
+  constructor() {
+    this.provider_tag = "in_memory";
+    this.store = /* @__PURE__ */ new Map();
+  }
+  async put(path, body, opts) {
+    if (opts?.ifNotExists && this.store.has(path)) throw new Error(`File exists: ${path}`);
+    const buf = Buffer.isBuffer(body) ? body : await streamToBuffer(body);
+    this.store.set(path, buf);
+    return { provider: this.provider_tag, native_id: path, size: buf.length };
+  }
+  async get(path) {
+    const buf = this.store.get(path);
+    if (!buf) throw new Error(`Not found: ${path}`);
+    return buf;
+  }
+  async delete(path) {
+    this.store.delete(path);
+  }
+  async exists(path) {
+    return this.store.has(path);
+  }
+  async getSignedUrl(path, _opts) {
+    const buf = this.store.get(path);
+    if (!buf) throw new Error(`Not found: ${path}`);
+    return `data:application/octet-stream;base64,${buf.toString("base64")}`;
+  }
+  async probe() {
+    return { ok: true };
+  }
+  /** Test-only escape hatch — exposes the internal store for assertions. */
+  snapshot() {
+    return new Map(this.store);
+  }
+};
+async function streamToBuffer(s) {
+  const chunks = [];
+  for await (const c of s) chunks.push(Buffer.isBuffer(c) ? c : Buffer.from(c));
+  return Buffer.concat(chunks);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  InMemoryProvider
+});

package/dist/testing/index.mjs

@@ -0,0 +1,44 @@
+// src/providers/in-memory.ts
+var InMemoryProvider = class {
+  constructor() {
+    this.provider_tag = "in_memory";
+    this.store = /* @__PURE__ */ new Map();
+  }
+  async put(path, body, opts) {
+    if (opts?.ifNotExists && this.store.has(path)) throw new Error(`File exists: ${path}`);
+    const buf = Buffer.isBuffer(body) ? body : await streamToBuffer(body);
+    this.store.set(path, buf);
+    return { provider: this.provider_tag, native_id: path, size: buf.length };
+  }
+  async get(path) {
+    const buf = this.store.get(path);
+    if (!buf) throw new Error(`Not found: ${path}`);
+    return buf;
+  }
+  async delete(path) {
+    this.store.delete(path);
+  }
+  async exists(path) {
+    return this.store.has(path);
+  }
+  async getSignedUrl(path, _opts) {
+    const buf = this.store.get(path);
+    if (!buf) throw new Error(`Not found: ${path}`);
+    return `data:application/octet-stream;base64,${buf.toString("base64")}`;
+  }
+  async probe() {
+    return { ok: true };
+  }
+  /** Test-only escape hatch — exposes the internal store for assertions. */
+  snapshot() {
+    return new Map(this.store);
+  }
+};
+async function streamToBuffer(s) {
+  const chunks = [];
+  for await (const c of s) chunks.push(Buffer.isBuffer(c) ? c : Buffer.from(c));
+  return Buffer.concat(chunks);
+}
+export {
+  InMemoryProvider
+};