@usegraft/assets 0.0.0-canary-20260831153011

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anderson Joseph
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# @usegraft/assets
+
+> S3-compatible object storage for binary assets. Cloudflare R2, MinIO, Tigris, or anything speaking the same API.
+
+Part of [Graft](https://github.com/AndersonDesign1/graft), a CMS built so an AI agent is the primary operator.
+
+## Install
+
+```bash
+npm i @usegraft/assets
+```
+
+## Use
+
+```ts
+import { createStorage, storageConfigFromEnv } from "@usegraft/assets";
+
+const storage = createStorage(storageConfigFromEnv());
+await storage.put(key, bytes, { contentType });
+const url = await storage.url(key);
+```
+
+`storageConfigFromEnv` reads `S3_BUCKET`, `S3_ENDPOINT`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY` and the optional `S3_PUBLIC_URL`. Set `S3_PUBLIC_URL` for a stable public base; without it, reads come back as presigned GETs.
+
+## Keys
+
+`defaultKeyFor` and `contentTypeFor` derive a content-addressed key and a MIME type from a filename, so an agent uploading a file does not have to invent either.
+
+```ts
+import { defaultKeyFor, contentTypeFor } from "@usegraft/assets";
+```
+
+Upload from the CLI with `graft asset put <file> [key]`, and reference the result from a collection with `field.asset()`.
+
+---
+
+MIT. [Repository](https://github.com/AndersonDesign1/graft) · [Changelog](https://github.com/AndersonDesign1/graft/blob/main/packages/assets/CHANGELOG.md)

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Storage configuration, read from S3-compatible env vars.
+ * Targets Cloudflare R2 by default; MinIO (docker) is the self-host alternative.
+ */
+interface StorageConfig {
+    endpoint: string;
+    region: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    bucket: string;
+    /**
+     * Public base URL for the bucket (e.g. an R2 public/custom domain). When set,
+     * `storage.url()` returns stable public URLs instead of presigned GETs.
+     */
+    publicBaseUrl?: string;
+}
+declare function storageConfigFromEnv(env?: Record<string, string | undefined>): StorageConfig;
+
+/** MIME type inferred from a file path or asset key extension. */
+declare function contentTypeFor(fileOrKey: string): string;
+/** Default key: assets/<lowercased filename>, sanitized to the asset-key alphabet. */
+declare function defaultKeyFor(file: string): string;
+
+interface PresignOptions {
+    expiresIn?: number;
+}
+interface Storage {
+    put(key: string, body: Uint8Array | string, contentType?: string): Promise<void>;
+    get(key: string): Promise<Uint8Array>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    /** A presigned PUT URL so a client (or agent) can upload directly. */
+    presignPut(key: string, options?: PresignOptions): Promise<string>;
+    /** A presigned GET URL for reading from a private bucket. */
+    presignGet(key: string, options?: PresignOptions): Promise<string>;
+    /**
+     * A renderable URL for the key: stable public URL when `publicBaseUrl` is
+     * configured, otherwise a presigned GET (default 900s expiry).
+     */
+    url(key: string, options?: PresignOptions): Promise<string>;
+}
+declare function createStorage(config?: StorageConfig): Storage;
+
+export { type PresignOptions, type Storage, type StorageConfig, contentTypeFor, createStorage, defaultKeyFor, storageConfigFromEnv };

package/dist/index.js

@@ -0,0 +1,101 @@
+// src/config.ts
+var REQUIRED = ["S3_ENDPOINT", "S3_ACCESS_KEY", "S3_SECRET_KEY", "S3_BUCKET"];
+function storageConfigFromEnv(env = process.env) {
+  const endpoint = env.S3_ENDPOINT;
+  const accessKeyId = env.S3_ACCESS_KEY;
+  const secretAccessKey = env.S3_SECRET_KEY;
+  const bucket = env.S3_BUCKET;
+  if (!endpoint || !accessKeyId || !secretAccessKey || !bucket) {
+    const missing = REQUIRED.find((key) => !env[key]);
+    throw new Error(`Missing required env ${missing}. Set it in .env (see .env.example).`);
+  }
+  return {
+    endpoint,
+    region: env.S3_REGION ?? "auto",
+    accessKeyId,
+    secretAccessKey,
+    bucket,
+    publicBaseUrl: env.S3_PUBLIC_URL
+  };
+}
+
+// src/keys.ts
+import { basename, extname } from "path";
+var CONTENT_TYPES = {
+  ".avif": "image/avif",
+  ".gif": "image/gif",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".pdf": "application/pdf",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".webp": "image/webp"
+};
+function contentTypeFor(fileOrKey) {
+  return CONTENT_TYPES[extname(fileOrKey).toLowerCase()] ?? "application/octet-stream";
+}
+function defaultKeyFor(file) {
+  const name = basename(file).toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[._-]+/, "");
+  return `assets/${name}`;
+}
+
+// src/storage.ts
+import { AwsClient } from "aws4fetch";
+function createStorage(config = storageConfigFromEnv()) {
+  const aws = new AwsClient({
+    accessKeyId: config.accessKeyId,
+    secretAccessKey: config.secretAccessKey,
+    region: config.region,
+    service: "s3"
+  });
+  const base = `${config.endpoint.replace(/\/+$/, "")}/${config.bucket}`;
+  const urlFor = (key) => `${base}/${key.split("/").map(encodeURIComponent).join("/")}`;
+  const presign = async (key, method, options) => {
+    const url = new URL(urlFor(key));
+    url.searchParams.set("X-Amz-Expires", String(options.expiresIn ?? 900));
+    const signed = await aws.sign(url.toString(), { method, aws: { signQuery: true } });
+    return signed.url;
+  };
+  return {
+    async put(key, body, contentType) {
+      const res = await aws.fetch(urlFor(key), {
+        method: "PUT",
+        body,
+        headers: contentType ? { "content-type": contentType } : void 0
+      });
+      if (!res.ok) throw new Error(`storage put failed (${res.status}): ${await res.text()}`);
+    },
+    async get(key) {
+      const res = await aws.fetch(urlFor(key));
+      if (!res.ok) throw new Error(`storage get failed (${res.status})`);
+      return new Uint8Array(await res.arrayBuffer());
+    },
+    async delete(key) {
+      const res = await aws.fetch(urlFor(key), { method: "DELETE" });
+      if (!res.ok && res.status !== 404) throw new Error(`storage delete failed (${res.status})`);
+    },
+    async exists(key) {
+      const res = await aws.fetch(urlFor(key), { method: "HEAD" });
+      return res.ok;
+    },
+    async presignPut(key, options = {}) {
+      return presign(key, "PUT", options);
+    },
+    async presignGet(key, options = {}) {
+      return presign(key, "GET", options);
+    },
+    async url(key, options = {}) {
+      if (config.publicBaseUrl) {
+        const publicBase = config.publicBaseUrl.replace(/\/+$/, "");
+        return `${publicBase}/${key.split("/").map(encodeURIComponent).join("/")}`;
+      }
+      return presign(key, "GET", options);
+    }
+  };
+}
+export {
+  contentTypeFor,
+  createStorage,
+  defaultKeyFor,
+  storageConfigFromEnv
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@usegraft/assets",
+  "version": "0.0.0-canary-20260831153011",
+  "description": "S3-compatible object storage for binary assets: Cloudflare R2, MinIO, Tigris.",
+  "keywords": [
+    "agent",
+    "ai",
+    "assets",
+    "cms",
+    "graft",
+    "headless-cms",
+    "mcp",
+    "minio",
+    "r2",
+    "s3",
+    "storage",
+    "typescript"
+  ],
+  "homepage": "https://github.com/AndersonDesign1/graft#readme",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AndersonDesign1/graft.git",
+    "directory": "packages/assets"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "aws4fetch": "^1.0.20"
+  },
+  "engines": {
+    "node": ">=22.16"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}