@amerged/ohmyhost-runtime 0.1.38 → 0.1.40

package/README.md

@@ -1,6 +1,6 @@
 # @amerged/ohmyhost-runtime
 
-ohmyho.st runtime client, version 0.1.38.
+ohmyho.st runtime client, version 0.1.40.
 
 ```sh
 npm install @amerged/ohmyhost-runtime

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./errors.js";
 export * from "./database.js";
 export * from "./mail.js";
+export * from "./mail-attachment.js";
 export * from "./storage.js";
 export type { GatewayConnection } from "./http.js";
 export * from "./mail-webhook.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AACnD,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AACnD,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -1,6 +1,7 @@
 export * from "./errors.js";
 export * from "./database.js";
 export * from "./mail.js";
+export * from "./mail-attachment.js";
 export * from "./storage.js";
 export * from "./mail-webhook.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAE7B,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAE7B,cAAc,mBAAmB,CAAC"}

package/dist/mail-attachment.d.ts

@@ -0,0 +1,14 @@
+import { type GatewayConnection } from "./http.js";
+export interface MailAttachmentDownloadOptions {
+    readonly signal?: AbortSignal;
+}
+/** Server-only receiving access using OHMYHOST_MAIL_KEY and global fetch. */
+export declare function createMailAttachmentClient(configuration: GatewayConnection & {
+    readonly projectId: string;
+    /** Optional expected environment; otherwise use the canonical metadata download_path scope. */
+    readonly environmentId?: string;
+}): Readonly<{
+    /** Consume to EOF for success, or cancel the stream when its bytes are no longer needed. */
+    download(downloadPath: string, options?: MailAttachmentDownloadOptions): Promise<ReadableStream<Uint8Array>>;
+}>;
+//# sourceMappingURL=mail-attachment.d.ts.map

package/dist/mail-attachment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mail-attachment.d.ts","sourceRoot":"","sources":["../src/mail-attachment.ts"],"names":[],"mappings":"AACA,OAAO,EAOL,KAAK,iBAAiB,EACvB,MAAM,WAAW,CAAC;AAEnB,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,6EAA6E;AAC7E,wBAAgB,0BAA0B,CACxC,aAAa,EAAE,iBAAiB,GAAG;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,+FAA+F;IAC/F,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;IAiBC,4FAA4F;2BAE5E,MAAM,YACX,6BAA6B,GACrC,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;GAgEzC"}

package/dist/mail-attachment.js

@@ -0,0 +1,186 @@
+import { CustomerRuntimeGatewayError } from "./errors.js";
+import { exactRecord, fetchWithTimeout, invalidResponse, requireConfiguredUlid, throwGatewayRelayError, validateGatewayConnection, } from "./http.js";
+/** Server-only receiving access using OHMYHOST_MAIL_KEY and global fetch. */
+export function createMailAttachmentClient(configuration) {
+    const connection = validateGatewayConnection(configuration);
+    const projectId = requireConfiguredUlid(configuration.projectId, "projectId", "OHMYHOST_PROJECT_ID");
+    const environmentId = configuration.environmentId === undefined
+        ? undefined
+        : requireConfiguredUlid(configuration.environmentId, "environmentId", "OHMYHOST_ENVIRONMENT_ID");
+    return Object.freeze({
+        /** Consume to EOF for success, or cancel the stream when its bytes are no longer needed. */
+        async download(downloadPath, options = {}) {
+            const match = typeof downloadPath === "string"
+                ? /^\/v1\/projects\/([0-7][0-9A-HJKMNP-TV-Z]{25})\/environments\/([0-7][0-9A-HJKMNP-TV-Z]{25})\/mail\/messages\/([0-7][0-9A-HJKMNP-TV-Z]{25})\/attachments\/([A-Za-z0-9_-]{1,128})$/u.exec(downloadPath)
+                : null;
+            if (match === null ||
+                match[1] !== projectId ||
+                (environmentId !== undefined && match[2] !== environmentId)) {
+                throw new CustomerRuntimeGatewayError("gateway_request_invalid", null, false);
+            }
+            const body = JSON.stringify({
+                project_id: projectId,
+                environment_id: match[2],
+                message_id: match[3],
+                attachment_id: match[4],
+            });
+            if (new TextEncoder().encode(body).byteLength > 1024) {
+                throw new CustomerRuntimeGatewayError("gateway_request_invalid", null, false);
+            }
+            const cancellation = new AbortController();
+            const signal = options.signal === undefined
+                ? cancellation.signal
+                : AbortSignal.any([cancellation.signal, options.signal]);
+            if (signal.aborted)
+                throw new CustomerRuntimeGatewayError("gateway_timeout", null, true);
+            const response = await fetchWithTimeout(connection.fetch, new Request(new URL("/v1/attachments/download", connection.endpoint), {
+                method: "POST",
+                headers: {
+                    authorization: `Bearer ${connection.key}`,
+                    "content-type": "application/json",
+                },
+                body,
+                signal,
+            }), connection.timeoutMilliseconds);
+            if (response.status !== 200) {
+                try {
+                    throwAttachmentError(response.status, await readAttachmentError(response, connection.timeoutMilliseconds));
+                }
+                finally {
+                    cancellation.abort();
+                }
+            }
+            if (response.body === null ||
+                response.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase() !==
+                    "application/octet-stream") {
+                cancellation.abort();
+                void response.body?.cancel().catch(ignoreCancellationError);
+                invalidResponse(response.status);
+            }
+            return attachmentStream(response.body, response.status, cancellation, signal);
+        },
+    });
+}
+/** A pull reads one source chunk; cancellation never drains or duplicates the attachment. */
+function attachmentStream(body, status, cancellation, signal) {
+    const source = body.getReader();
+    let finished = false;
+    let abort;
+    function finish(cancel) {
+        if (finished)
+            return;
+        finished = true;
+        signal.removeEventListener("abort", abort);
+        if (cancel) {
+            cancellation.abort();
+            void source.cancel().catch(ignoreCancellationError);
+        }
+        source.releaseLock();
+    }
+    return new ReadableStream({
+        start(controller) {
+            abort = () => {
+                controller.error(new CustomerRuntimeGatewayError("gateway_timeout", status, true));
+                finish(true);
+            };
+            if (signal.aborted)
+                abort();
+            else
+                signal.addEventListener("abort", abort, { once: true });
+        },
+        async pull(controller) {
+            try {
+                const next = await source.read();
+                if (finished)
+                    return;
+                if (next.done) {
+                    finish(false);
+                    controller.close();
+                }
+                else if (next.value instanceof Uint8Array) {
+                    controller.enqueue(next.value);
+                }
+                else {
+                    invalidResponse(status);
+                }
+            }
+            catch {
+                if (finished)
+                    return;
+                finish(true);
+                controller.error(new CustomerRuntimeGatewayError("gateway_unavailable", status, true));
+            }
+        },
+        cancel() {
+            finish(true);
+        },
+    }, { highWaterMark: 0 });
+}
+/** Only small error records are buffered; binary successes never enter this parser. */
+async function readAttachmentError(response, timeoutMilliseconds) {
+    const declared = response.headers.get("content-length");
+    if (response.headers.get("content-type")?.split(";", 1)[0]?.trim() !== "application/json" ||
+        response.body === null ||
+        (declared !== null && (!/^[0-9]+$/u.test(declared) || Number(declared) > 1024))) {
+        void response.body?.cancel().catch(ignoreCancellationError);
+        invalidResponse(response.status);
+    }
+    const source = response.body.getReader();
+    const bytes = new Uint8Array(1024);
+    let length = 0;
+    let finished = false;
+    let timer;
+    try {
+        const expired = new Promise((_resolve, reject) => {
+            timer = setTimeout(() => reject(new CustomerRuntimeGatewayError("gateway_timeout", response.status, true)), timeoutMilliseconds);
+        });
+        for (;;) {
+            const next = await Promise.race([source.read(), expired]);
+            if (next.done) {
+                finished = true;
+                break;
+            }
+            if (!(next.value instanceof Uint8Array) || length + next.value.byteLength > bytes.byteLength)
+                invalidResponse(response.status);
+            bytes.set(next.value, length);
+            length += next.value.byteLength;
+        }
+        try {
+            return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, length)));
+        }
+        catch {
+            return invalidResponse(response.status);
+        }
+    }
+    catch (error) {
+        if (error instanceof CustomerRuntimeGatewayError)
+            throw error;
+        throw new CustomerRuntimeGatewayError("gateway_unavailable", response.status, true);
+    }
+    finally {
+        clearTimeout(timer);
+        if (!finished)
+            void source.cancel().catch(ignoreCancellationError);
+        source.releaseLock();
+    }
+}
+function ignoreCancellationError() {
+    // The original download failure remains the public error.
+}
+function throwAttachmentError(status, body) {
+    throwGatewayRelayError(status, body);
+    const record = exactRecord(body, ["code"], status);
+    const code = record["code"];
+    if (status === 400 && code === "invalid_request")
+        throw new CustomerRuntimeGatewayError("gateway_request_invalid", status, false);
+    if (status === 401 && code === "unauthorized")
+        throw new CustomerRuntimeGatewayError("unauthorized", status, false);
+    if (status === 404 && code === "resource_not_found")
+        throw new CustomerRuntimeGatewayError("mail_message_not_found", status, false);
+    if (status === 410 && code === "mail_content_expired")
+        throw new CustomerRuntimeGatewayError("mail_content_expired", status, false);
+    if (status === 413 && code === "mail_attachment_too_large")
+        throw new CustomerRuntimeGatewayError("mail_attachment_too_large", status, false);
+    return invalidResponse(status);
+}
+//# sourceMappingURL=mail-attachment.js.map

package/dist/mail-attachment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mail-attachment.js","sourceRoot":"","sources":["../src/mail-attachment.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amerged/ohmyhost-runtime",
-  "version": "0.1.38",
+  "version": "0.1.40",
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -22,6 +22,10 @@
       "types": "./dist/mail.d.ts",
       "import": "./dist/mail.js"
     },
+    "./mail-attachment": {
+      "types": "./dist/mail-attachment.d.ts",
+      "import": "./dist/mail-attachment.js"
+    },
     "./database": {
       "types": "./dist/database.d.ts",
       "import": "./dist/database.js"

package/src/packages/customer-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ohmyhost/customer-runtime",
-  "version": "0.1.38",
+  "version": "0.1.40",
   "private": true,
   "type": "module",
   "sideEffects": false,
@@ -15,6 +15,11 @@
       "types": "./dist/mail.d.ts",
       "import": "./dist/mail.js"
     },
+    "./mail-attachment": {
+      "source": "./src/mail-attachment.ts",
+      "types": "./dist/mail-attachment.d.ts",
+      "import": "./dist/mail-attachment.js"
+    },
     "./database": {
       "source": "./src/database.ts",
       "types": "./dist/database.d.ts",
@@ -52,7 +57,7 @@
   },
   "devDependencies": {
     "kysely": "0.29.5",
-    "better-auth": "1.7.1"
+    "better-auth": "1.7.7"
   },
   "license": "Apache-2.0"
 }

package/src/packages/customer-runtime/src/index.ts

@@ -1,6 +1,7 @@
 export * from "./errors.js";
 export * from "./database.js";
 export * from "./mail.js";
+export * from "./mail-attachment.js";
 export * from "./storage.js";
 export type { GatewayConnection } from "./http.js";
 export * from "./mail-webhook.js";

package/src/packages/customer-runtime/src/mail-attachment.ts

@@ -0,0 +1,238 @@
+import { CustomerRuntimeGatewayError } from "./errors.js";
+import {
+  exactRecord,
+  fetchWithTimeout,
+  invalidResponse,
+  requireConfiguredUlid,
+  throwGatewayRelayError,
+  validateGatewayConnection,
+  type GatewayConnection,
+} from "./http.js";
+
+export interface MailAttachmentDownloadOptions {
+  readonly signal?: AbortSignal;
+}
+
+/** Server-only receiving access using OHMYHOST_MAIL_KEY and global fetch. */
+export function createMailAttachmentClient(
+  configuration: GatewayConnection & {
+    readonly projectId: string;
+    /** Optional expected environment; otherwise use the canonical metadata download_path scope. */
+    readonly environmentId?: string;
+  },
+) {
+  const connection = validateGatewayConnection(configuration);
+  const projectId = requireConfiguredUlid(
+    configuration.projectId,
+    "projectId",
+    "OHMYHOST_PROJECT_ID",
+  );
+  const environmentId =
+    configuration.environmentId === undefined
+      ? undefined
+      : requireConfiguredUlid(
+          configuration.environmentId,
+          "environmentId",
+          "OHMYHOST_ENVIRONMENT_ID",
+        );
+  return Object.freeze({
+    /** Consume to EOF for success, or cancel the stream when its bytes are no longer needed. */
+    async download(
+      downloadPath: string,
+      options: MailAttachmentDownloadOptions = {},
+    ): Promise<ReadableStream<Uint8Array>> {
+      const match =
+        typeof downloadPath === "string"
+          ? /^\/v1\/projects\/([0-7][0-9A-HJKMNP-TV-Z]{25})\/environments\/([0-7][0-9A-HJKMNP-TV-Z]{25})\/mail\/messages\/([0-7][0-9A-HJKMNP-TV-Z]{25})\/attachments\/([A-Za-z0-9_-]{1,128})$/u.exec(
+              downloadPath,
+            )
+          : null;
+      if (
+        match === null ||
+        match[1] !== projectId ||
+        (environmentId !== undefined && match[2] !== environmentId)
+      ) {
+        throw new CustomerRuntimeGatewayError("gateway_request_invalid", null, false);
+      }
+      const body = JSON.stringify({
+        project_id: projectId,
+        environment_id: match[2],
+        message_id: match[3],
+        attachment_id: match[4],
+      });
+      if (new TextEncoder().encode(body).byteLength > 1024) {
+        throw new CustomerRuntimeGatewayError("gateway_request_invalid", null, false);
+      }
+      const cancellation = new AbortController();
+      const signal =
+        options.signal === undefined
+          ? cancellation.signal
+          : AbortSignal.any([cancellation.signal, options.signal]);
+      if (signal.aborted) throw new CustomerRuntimeGatewayError("gateway_timeout", null, true);
+      const response = await fetchWithTimeout(
+        connection.fetch,
+        new Request(new URL("/v1/attachments/download", connection.endpoint), {
+          method: "POST",
+          headers: {
+            authorization: `Bearer ${connection.key}`,
+            "content-type": "application/json",
+          },
+          body,
+          signal,
+        }),
+        connection.timeoutMilliseconds,
+      );
+      if (response.status !== 200) {
+        try {
+          throwAttachmentError(
+            response.status,
+            await readAttachmentError(response, connection.timeoutMilliseconds),
+          );
+        } finally {
+          cancellation.abort();
+        }
+      }
+      if (
+        response.body === null ||
+        response.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase() !==
+          "application/octet-stream"
+      ) {
+        cancellation.abort();
+        void response.body?.cancel().catch(ignoreCancellationError);
+        invalidResponse(response.status);
+      }
+      return attachmentStream(response.body, response.status, cancellation, signal);
+    },
+  });
+}
+
+/** A pull reads one source chunk; cancellation never drains or duplicates the attachment. */
+function attachmentStream(
+  body: ReadableStream<Uint8Array>,
+  status: number,
+  cancellation: AbortController,
+  signal: AbortSignal,
+): ReadableStream<Uint8Array> {
+  const source = body.getReader();
+  let finished = false;
+  let abort: () => void;
+  function finish(cancel: boolean) {
+    if (finished) return;
+    finished = true;
+    signal.removeEventListener("abort", abort);
+    if (cancel) {
+      cancellation.abort();
+      void source.cancel().catch(ignoreCancellationError);
+    }
+    source.releaseLock();
+  }
+  return new ReadableStream<Uint8Array>(
+    {
+      start(controller) {
+        abort = () => {
+          controller.error(new CustomerRuntimeGatewayError("gateway_timeout", status, true));
+          finish(true);
+        };
+        if (signal.aborted) abort();
+        else signal.addEventListener("abort", abort, { once: true });
+      },
+      async pull(controller) {
+        try {
+          const next = await source.read();
+          if (finished) return;
+          if (next.done) {
+            finish(false);
+            controller.close();
+          } else if (next.value instanceof Uint8Array) {
+            controller.enqueue(next.value);
+          } else {
+            invalidResponse(status);
+          }
+        } catch {
+          if (finished) return;
+          finish(true);
+          controller.error(new CustomerRuntimeGatewayError("gateway_unavailable", status, true));
+        }
+      },
+      cancel() {
+        finish(true);
+      },
+    },
+    { highWaterMark: 0 },
+  );
+}
+
+/** Only small error records are buffered; binary successes never enter this parser. */
+async function readAttachmentError(
+  response: Response,
+  timeoutMilliseconds: number,
+): Promise<unknown> {
+  const declared = response.headers.get("content-length");
+  if (
+    response.headers.get("content-type")?.split(";", 1)[0]?.trim() !== "application/json" ||
+    response.body === null ||
+    (declared !== null && (!/^[0-9]+$/u.test(declared) || Number(declared) > 1024))
+  ) {
+    void response.body?.cancel().catch(ignoreCancellationError);
+    invalidResponse(response.status);
+  }
+  const source = response.body.getReader();
+  const bytes = new Uint8Array(1024);
+  let length = 0;
+  let finished = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const expired = new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(
+        () => reject(new CustomerRuntimeGatewayError("gateway_timeout", response.status, true)),
+        timeoutMilliseconds,
+      );
+    });
+    for (;;) {
+      const next = await Promise.race([source.read(), expired]);
+      if (next.done) {
+        finished = true;
+        break;
+      }
+      if (!(next.value instanceof Uint8Array) || length + next.value.byteLength > bytes.byteLength)
+        invalidResponse(response.status);
+      bytes.set(next.value, length);
+      length += next.value.byteLength;
+    }
+    try {
+      return JSON.parse(
+        new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, length)),
+      ) as unknown;
+    } catch {
+      return invalidResponse(response.status);
+    }
+  } catch (error) {
+    if (error instanceof CustomerRuntimeGatewayError) throw error;
+    throw new CustomerRuntimeGatewayError("gateway_unavailable", response.status, true);
+  } finally {
+    clearTimeout(timer);
+    if (!finished) void source.cancel().catch(ignoreCancellationError);
+    source.releaseLock();
+  }
+}
+
+function ignoreCancellationError(): void {
+  // The original download failure remains the public error.
+}
+
+function throwAttachmentError(status: number, body: unknown): never {
+  throwGatewayRelayError(status, body);
+  const record = exactRecord(body, ["code"], status);
+  const code = record["code"];
+  if (status === 400 && code === "invalid_request")
+    throw new CustomerRuntimeGatewayError("gateway_request_invalid", status, false);
+  if (status === 401 && code === "unauthorized")
+    throw new CustomerRuntimeGatewayError("unauthorized", status, false);
+  if (status === 404 && code === "resource_not_found")
+    throw new CustomerRuntimeGatewayError("mail_message_not_found", status, false);
+  if (status === 410 && code === "mail_content_expired")
+    throw new CustomerRuntimeGatewayError("mail_content_expired", status, false);
+  if (status === 413 && code === "mail_attachment_too_large")
+    throw new CustomerRuntimeGatewayError("mail_attachment_too_large", status, false);
+  return invalidResponse(status);
+}