@nymbalhq/media-s3 0.0.0-stage → 1.1.0

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+import { MediaStorage, AdapterContext } from '@nymbalhq/types';
+
+/** Where the URL of an object starts, and where its key starts in the bucket. */
+interface S3ObjectUrlOptions {
+    bucket: string;
+    /** `us-east-1` when not given. */
+    region?: string;
+    /** An S3-compatible API (MinIO, R2); its objects are served path-style under it. */
+    endpoint?: string;
+    /** Prepended to every key, its edge slashes trimmed; none when empty. */
+    prefix?: string;
+    /** Where the bucket's objects are served from (a CDN), when not the bucket's own URL. */
+    publicUrl?: string;
+}
+interface S3MediaStorageOptions extends S3ObjectUrlOptions {
+    /** True by default when an endpoint is set: an S3-compatible server rarely has per-bucket hostnames. */
+    forcePathStyle?: boolean;
+    /** For tests only: a store gets its credentials from the AWS SDK's default chain. */
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+}
+declare const S3_MEDIA_CAPABILITIES: readonly string[];
+declare const DEFAULT_S3_REGION = "us-east-1";
+/** The public URL of the object stored under `key`: the base, then each segment of the object key percent-encoded. */
+declare function s3ObjectUrl(options: S3ObjectUrlOptions, key: string): string;
+/**
+ * Media stored as objects in a bucket the operator owns: it never creates buckets or sets policies, so the bucket (or
+ * the `publicUrl` in front of it) must already serve its objects publicly.
+ */
+declare function createS3MediaStorage(options: S3MediaStorageOptions): MediaStorage;
+
+/**
+ * The kernel's entry: `infrastructure.media: 's3'`, with the `s3` block as the platform resolved it (its environment
+ * fallbacks and defaults applied). Credentials are never in it: the AWS SDK's default chain provides them.
+ */
+declare function createAdapter(ctx: AdapterContext): MediaStorage;
+
+export { DEFAULT_S3_REGION, type S3MediaStorageOptions, type S3ObjectUrlOptions, S3_MEDIA_CAPABILITIES, createAdapter, createS3MediaStorage, s3ObjectUrl };

package/dist/index.js

@@ -0,0 +1,98 @@
+// src/index.ts
+import { ConfigError } from "@nymbalhq/types";
+
+// src/s3-media-storage.ts
+import { HeadBucketCommand, PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
+import { boundedHealthCheck } from "@nymbalhq/types";
+var S3_MEDIA_CAPABILITIES = ["put"];
+var DEFAULT_S3_REGION = "us-east-1";
+var trimTrailingSlashes = (s) => s.replace(/\/+$/, "");
+function objectKey(prefix, key) {
+  const trimmed = (prefix ?? "").replace(/^\/+|\/+$/g, "");
+  return trimmed === "" ? key : `${trimmed}/${key}`;
+}
+function baseUrl(options) {
+  if (options.publicUrl !== void 0) return trimTrailingSlashes(options.publicUrl);
+  if (options.endpoint !== void 0) {
+    return `${trimTrailingSlashes(options.endpoint)}/${options.bucket}`;
+  }
+  return `https://${options.bucket}.s3.${options.region ?? DEFAULT_S3_REGION}.amazonaws.com`;
+}
+function s3ObjectUrl(options, key) {
+  const path = objectKey(options.prefix, key).split("/").map(encodeURIComponent).join("/");
+  return `${baseUrl(options)}/${path}`;
+}
+function createS3MediaStorage(options) {
+  const client = new S3Client({
+    region: options.region ?? DEFAULT_S3_REGION,
+    forcePathStyle: options.forcePathStyle ?? options.endpoint !== void 0,
+    ...options.endpoint !== void 0 && { endpoint: options.endpoint },
+    ...options.credentials !== void 0 && { credentials: options.credentials }
+  });
+  return {
+    capabilities: () => S3_MEDIA_CAPABILITIES,
+    async put(key, body, contentType) {
+      await client.send(
+        new PutObjectCommand({
+          Bucket: options.bucket,
+          Key: objectKey(options.prefix, key),
+          Body: body,
+          ContentType: contentType
+        })
+      );
+      return { url: s3ObjectUrl(options, key) };
+    },
+    // HeadBucket reads the bucket's existence and our access to it; aborted at the bound, retries included.
+    healthCheck() {
+      return boundedHealthCheck(
+        async (signal) => {
+          await client.send(new HeadBucketCommand({ Bucket: options.bucket }), {
+            abortSignal: signal
+          });
+          return { status: "healthy", detail: options.bucket };
+        },
+        {
+          redact: [
+            options.credentials?.accessKeyId ?? "",
+            options.credentials?.secretAccessKey ?? ""
+          ]
+        }
+      );
+    }
+  };
+}
+
+// src/index.ts
+var optionalString = (value) => typeof value === "string" && value !== "" ? value : void 0;
+function createAdapter(ctx) {
+  if (ctx.slot !== "media") {
+    throw new ConfigError(`@nymbalhq/media-s3 serves media, not ${ctx.slot}`, {
+      code: "adapter.wrong_slot",
+      context: { slot: ctx.slot }
+    });
+  }
+  const bucket = optionalString(ctx.config["bucket"]);
+  if (bucket === void 0) {
+    throw new ConfigError("@nymbalhq/media-s3 needs a bucket", {
+      code: "config.invalid",
+      context: { slot: ctx.slot }
+    });
+  }
+  const options = { bucket };
+  for (const field of ["region", "endpoint", "prefix", "publicUrl"]) {
+    const value = optionalString(ctx.config[field]);
+    if (value !== void 0) options[field] = value;
+  }
+  if (typeof ctx.config["forcePathStyle"] === "boolean") {
+    options.forcePathStyle = ctx.config["forcePathStyle"];
+  }
+  return createS3MediaStorage(options);
+}
+export {
+  DEFAULT_S3_REGION,
+  S3_MEDIA_CAPABILITIES,
+  createAdapter,
+  createS3MediaStorage,
+  s3ObjectUrl
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/s3-media-storage.ts"],"sourcesContent":["import { ConfigError, type AdapterContext, type MediaStorage } from '@nymbalhq/types'\nimport { createS3MediaStorage, type S3MediaStorageOptions } from './s3-media-storage.js'\n\nexport {\n  createS3MediaStorage,\n  DEFAULT_S3_REGION,\n  S3_MEDIA_CAPABILITIES,\n  s3ObjectUrl,\n  type S3MediaStorageOptions,\n  type S3ObjectUrlOptions,\n} from './s3-media-storage.js'\n\nconst optionalString = (value: unknown): string | undefined =>\n  typeof value === 'string' && value !== '' ? value : undefined\n\n/**\n * The kernel's entry: `infrastructure.media: 's3'`, with the `s3` block as the platform resolved it (its environment\n * fallbacks and defaults applied). Credentials are never in it: the AWS SDK's default chain provides them.\n */\nexport function createAdapter(ctx: AdapterContext): MediaStorage {\n  if (ctx.slot !== 'media') {\n    throw new ConfigError(`@nymbalhq/media-s3 serves media, not ${ctx.slot}`, {\n      code: 'adapter.wrong_slot',\n      context: { slot: ctx.slot },\n    })\n  }\n  const bucket = optionalString(ctx.config['bucket'])\n  if (bucket === undefined) {\n    throw new ConfigError('@nymbalhq/media-s3 needs a bucket', {\n      code: 'config.invalid',\n      context: { slot: ctx.slot },\n    })\n  }\n  const options: S3MediaStorageOptions = { bucket }\n  for (const field of ['region', 'endpoint', 'prefix', 'publicUrl'] as const) {\n    const value = optionalString(ctx.config[field])\n    if (value !== undefined) options[field] = value\n  }\n  if (typeof ctx.config['forcePathStyle'] === 'boolean') {\n    options.forcePathStyle = ctx.config['forcePathStyle']\n  }\n  return createS3MediaStorage(options)\n}\n","import { HeadBucketCommand, PutObjectCommand, S3Client } from '@aws-sdk/client-s3'\nimport { boundedHealthCheck, type HealthReport, type MediaStorage } from '@nymbalhq/types'\n\n/** Where the URL of an object starts, and where its key starts in the bucket. */\nexport interface S3ObjectUrlOptions {\n  bucket: string\n  /** `us-east-1` when not given. */\n  region?: string\n  /** An S3-compatible API (MinIO, R2); its objects are served path-style under it. */\n  endpoint?: string\n  /** Prepended to every key, its edge slashes trimmed; none when empty. */\n  prefix?: string\n  /** Where the bucket's objects are served from (a CDN), when not the bucket's own URL. */\n  publicUrl?: string\n}\n\nexport interface S3MediaStorageOptions extends S3ObjectUrlOptions {\n  /** True by default when an endpoint is set: an S3-compatible server rarely has per-bucket hostnames. */\n  forcePathStyle?: boolean\n  /** For tests only: a store gets its credentials from the AWS SDK's default chain. */\n  credentials?: { accessKeyId: string; secretAccessKey: string }\n}\n\nexport const S3_MEDIA_CAPABILITIES: readonly string[] = ['put']\n\nexport const DEFAULT_S3_REGION = 'us-east-1'\n\nconst trimTrailingSlashes = (s: string): string => s.replace(/\\/+$/, '')\n\n/** The object's key in the bucket. Only the prefix is normalised: the key stays verbatim, so distinct keys stay distinct objects. */\nfunction objectKey(prefix: string | undefined, key: string): string {\n  const trimmed = (prefix ?? '').replace(/^\\/+|\\/+$/g, '')\n  return trimmed === '' ? key : `${trimmed}/${key}`\n}\n\nfunction baseUrl(options: S3ObjectUrlOptions): string {\n  if (options.publicUrl !== undefined) return trimTrailingSlashes(options.publicUrl)\n  if (options.endpoint !== undefined) {\n    return `${trimTrailingSlashes(options.endpoint)}/${options.bucket}`\n  }\n  return `https://${options.bucket}.s3.${options.region ?? DEFAULT_S3_REGION}.amazonaws.com`\n}\n\n/** The public URL of the object stored under `key`: the base, then each segment of the object key percent-encoded. */\nexport function s3ObjectUrl(options: S3ObjectUrlOptions, key: string): string {\n  const path = objectKey(options.prefix, key).split('/').map(encodeURIComponent).join('/')\n  return `${baseUrl(options)}/${path}`\n}\n\n/**\n * Media stored as objects in a bucket the operator owns: it never creates buckets or sets policies, so the bucket (or\n * the `publicUrl` in front of it) must already serve its objects publicly.\n */\nexport function createS3MediaStorage(options: S3MediaStorageOptions): MediaStorage {\n  const client = new S3Client({\n    region: options.region ?? DEFAULT_S3_REGION,\n    forcePathStyle: options.forcePathStyle ?? options.endpoint !== undefined,\n    ...(options.endpoint !== undefined && { endpoint: options.endpoint }),\n    ...(options.credentials !== undefined && { credentials: options.credentials }),\n  })\n  return {\n    capabilities: () => S3_MEDIA_CAPABILITIES,\n    async put(key, body, contentType) {\n      await client.send(\n        new PutObjectCommand({\n          Bucket: options.bucket,\n          Key: objectKey(options.prefix, key),\n          Body: body,\n          ContentType: contentType,\n        }),\n      )\n      return { url: s3ObjectUrl(options, key) }\n    },\n    // HeadBucket reads the bucket's existence and our access to it; aborted at the bound, retries included.\n    healthCheck(): Promise<HealthReport> {\n      return boundedHealthCheck(\n        async (signal) => {\n          await client.send(new HeadBucketCommand({ Bucket: options.bucket }), {\n            abortSignal: signal,\n          })\n          return { status: 'healthy', detail: options.bucket }\n        },\n        {\n          redact: [\n            options.credentials?.accessKeyId ?? '',\n            options.credentials?.secretAccessKey ?? '',\n          ],\n        },\n      )\n    },\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@nymbalhq/media-s3",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.1.0",
+  "description": "S3 media storage for Nymbal: `infrastructure.media: 's3'`, on AWS or any S3-compatible bucket",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nymbalhq/nymbal.git",
+    "directory": "packages/media-s3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./recipes/*": "./recipes/*"
+  },
+  "files": [
+    "dist",
+    "recipes"
+  ],
+  "dependencies": {
+    "@nymbalhq/types": "1.1.0"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-s3": "^3.600.0"
+  },
+  "devDependencies": {
+    "@aws-sdk/client-s3": "^3.1153.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
 }

package/recipes/s3.json

@@ -0,0 +1,54 @@
+{
+  "name": "s3",
+  "summary": "Store product images and other media in an S3-compatible bucket (AWS S3, R2, MinIO).",
+  "install": ["@nymbalhq/media-s3", "@aws-sdk/client-s3"],
+  "set": [{ "path": "infrastructure.media", "value": "s3" }],
+  "env": [
+    {
+      "name": "S3_BUCKET",
+      "example": "my-store-media",
+      "required": true,
+      "comment": "The bucket media is stored in; it must already serve its objects publicly"
+    },
+    {
+      "name": "S3_ENDPOINT",
+      "example": "http://localhost:9000",
+      "required": false,
+      "comment": "An S3-compatible API (MinIO, R2); leave unset for AWS"
+    },
+    {
+      "name": "S3_PUBLIC_URL",
+      "example": "https://media.example.com",
+      "required": false,
+      "comment": "Where the bucket's objects are served from (a CDN); defaults to the bucket's own URL"
+    },
+    {
+      "name": "NYMBAL_S3_PREFIX",
+      "example": "media",
+      "required": false,
+      "comment": "Starts every object key; none by default"
+    },
+    {
+      "name": "AWS_REGION",
+      "example": "us-east-1",
+      "required": false,
+      "comment": "The bucket's region (default us-east-1)"
+    },
+    {
+      "name": "AWS_ACCESS_KEY_ID",
+      "example": "",
+      "required": false,
+      "comment": "Credentials for the AWS SDK; a profile or a role works instead"
+    },
+    {
+      "name": "AWS_SECRET_ACCESS_KEY",
+      "example": "",
+      "required": false,
+      "comment": "The secret for AWS_ACCESS_KEY_ID"
+    }
+  ],
+  "next": [
+    "Create the bucket and let it serve its objects publicly: the store never creates buckets or sets policies.",
+    "Give the AWS SDK credentials: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY in .env, a profile or a role."
+  ]
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.