getaiapi 0.2.0 → 0.3.1

package/README.md

@@ -262,7 +262,10 @@ Resolves a model by name. Accepts canonical names, aliases, and normalized varia
 
 ## R2 Storage (Asset Uploads)
 
-Some providers can't fetch from private or presigned URLs. getaiapi includes built-in Cloudflare R2 storage support that automatically uploads binary assets to a public bucket before sending them to providers.
+getaiapi includes built-in Cloudflare R2 storage support that automatically uploads binary assets before sending them to providers. Two modes are supported:
+
+- **`public`** (default) — requires a publicly readable bucket; returns public URLs (via `publicUrlBase` or the R2 endpoint)
+- **`presigned`** — works with private buckets; returns time-limited presigned GET URLs signed with S3 Signature V4 (no public access needed, `publicUrlBase` is not required)
 
 ### Setup
 
@@ -275,10 +278,26 @@ export R2_BUCKET_NAME="your-bucket-name"
 export R2_ACCESS_KEY_ID="your-r2-access-key"
 export R2_SECRET_ACCESS_KEY="your-r2-secret-key"
 
-# Optional - custom public URL (e.g. CDN domain mapped to your bucket)
+# Optional - custom public URL (only needed for mode: 'public')
 export R2_PUBLIC_URL="https://cdn.example.com"
+
+# Optional - use presigned URLs for private buckets (default: 'public')
+export R2_STORAGE_MODE="presigned"
+export R2_PRESIGN_EXPIRES_IN="3600"  # seconds, default: 3600, max: 604800 (7 days)
 ```
 
+#### How to get your R2 Public URL (public mode only)
+
+If using `mode: 'presigned'`, you can skip this — no public bucket access is needed.
+
+1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com)
+2. Go to **R2 Object Storage** in the left sidebar
+3. Click on your bucket
+4. Go to the **Settings** tab
+5. Under **Public access**, click **Allow Access**
+6. Cloudflare will provide a public URL like `https://<bucket>.<account-id>.r2.dev` — use this as your `R2_PUBLIC_URL`
+7. (Optional) You can also connect a **Custom Domain** under the same section for a cleaner URL like `https://cdn.yourdomain.com`
+
 Then call `configureStorage()` once at startup:
 
 ```typescript
@@ -295,6 +314,8 @@ configureStorage({
   secretAccessKey: 'your-secret',
   publicUrlBase: 'https://cdn.example.com', // optional
   autoUpload: false,                         // optional
+  mode: 'public',                            // 'public' | 'presigned' (default: 'public')
+  presignExpiresIn: 3600,                    // presigned URL TTL in seconds (default: 3600)
 })
 ```
 
@@ -352,6 +373,38 @@ console.log(url) // https://cdn.example.com/uploads/a1b2c3d4-...
 await deleteAsset(key)
 ```
 
+### Presigned URLs (Private Buckets)
+
+If your R2 bucket doesn't have public read access, use presigned mode. Instead of returning a public URL, `uploadAsset` will return a time-limited presigned GET URL signed with S3 Signature V4.
+
+```typescript
+configureStorage({
+  accountId: 'your-account-id',
+  bucketName: 'private-bucket',
+  accessKeyId: 'your-key',
+  secretAccessKey: 'your-secret',
+  mode: 'presigned',          // uploadAsset returns presigned URLs
+  presignExpiresIn: 1800,     // URLs expire after 30 minutes
+})
+
+const { url } = await uploadAsset(Buffer.from('secret data'), {
+  contentType: 'application/octet-stream',
+})
+// url is a presigned GET URL, valid for 30 minutes
+```
+
+You can also generate presigned URLs for existing objects:
+
+```typescript
+import { presignAsset } from 'getaiapi'
+
+const url = presignAsset('uploads/my-file.png')
+// => https://<account>.r2.cloudflarestorage.com/<bucket>/uploads/my-file.png?X-Amz-Algorithm=...
+
+// Custom expiry per-call (overrides config default)
+const shortUrl = presignAsset('uploads/my-file.png', { expiresIn: 300 }) // 5 minutes
+```
+
 **UploadOptions**
 
 | Option | Type | Description |

package/dist/{chunk-RPORXMST.js → chunk-RC2KZLI2.js}

@@ -1355,9 +1355,56 @@ function signS3Request(method, url, headers, body, credentials) {
     }
   };
 }
+function presignS3Url(url, credentials, options) {
+  const region = credentials.region ?? "auto";
+  const service = "s3";
+  const parsedUrl = new URL(url);
+  const now = /* @__PURE__ */ new Date();
+  const { amzDate, dateStamp } = toAmzDate(now);
+  const expiresIn = options?.expiresIn ?? 3600;
+  const host = parsedUrl.host;
+  const signedHeaders = "host";
+  const scope = `${dateStamp}/${region}/${service}/aws4_request`;
+  const credential = `${credentials.accessKeyId}/${scope}`;
+  const queryParams = new URLSearchParams({
+    "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
+    "X-Amz-Credential": credential,
+    "X-Amz-Date": amzDate,
+    "X-Amz-Expires": String(expiresIn),
+    "X-Amz-SignedHeaders": signedHeaders
+  });
+  const canonicalRequest = [
+    "GET",
+    parsedUrl.pathname,
+    queryParams.toString(),
+    `host:${host}
+`,
+    signedHeaders,
+    "UNSIGNED-PAYLOAD"
+  ].join("\n");
+  const stringToSign = [
+    "AWS4-HMAC-SHA256",
+    amzDate,
+    scope,
+    sha256(canonicalRequest)
+  ].join("\n");
+  const signingKey = getSigningKey(credentials.secretAccessKey, dateStamp, region, service);
+  const signature = createHmac("sha256", signingKey).update(stringToSign).digest("hex");
+  queryParams.set("X-Amz-Signature", signature);
+  return `${parsedUrl.origin}${parsedUrl.pathname}?${queryParams.toString()}`;
+}
 
 // src/storage.ts
+var MAX_PRESIGN_EXPIRES = 604800;
 var storageConfig = null;
+function parseExpiresIn(value) {
+  if (!value) return void 0;
+  const parsed = parseInt(value, 10);
+  if (Number.isNaN(parsed) || parsed <= 0) {
+    throw new StorageError("config", `Invalid R2_PRESIGN_EXPIRES_IN: "${value}". Must be a positive integer.`);
+  }
+  return parsed;
+}
 function configureStorage(config) {
   if (config) {
     storageConfig = config;
@@ -1379,7 +1426,9 @@ function configureStorage(config) {
     accessKeyId,
     secretAccessKey,
     publicUrlBase: process.env.R2_PUBLIC_URL,
-    autoUpload: false
+    autoUpload: false,
+    mode: process.env.R2_STORAGE_MODE === "presigned" ? "presigned" : void 0,
+    presignExpiresIn: parseExpiresIn(process.env.R2_PRESIGN_EXPIRES_IN)
   };
 }
 function getStorageConfig() {
@@ -1445,13 +1494,31 @@ async function uploadAsset(input, options) {
     const body = await response.text().catch(() => "");
     throw new StorageError("upload", `R2 returned ${response.status}: ${body}`, response.status);
   }
+  const url = config.mode === "presigned" ? validatedPresign(config, key) : buildPublicUrl(config, key);
   return {
-    url: buildPublicUrl(config, key),
+    url,
     key,
     size_bytes: buffer.length,
     content_type: contentType
   };
 }
+function validatedPresign(config, key, expiresIn) {
+  const ttl = expiresIn ?? config.presignExpiresIn ?? 3600;
+  if (ttl > MAX_PRESIGN_EXPIRES) {
+    throw new StorageError(
+      "config",
+      `Presign expiry ${ttl}s exceeds maximum of ${MAX_PRESIGN_EXPIRES}s (7 days).`
+    );
+  }
+  return presignS3Url(buildR2Url(config, key), {
+    accessKeyId: config.accessKeyId,
+    secretAccessKey: config.secretAccessKey
+  }, { expiresIn: ttl });
+}
+function presignAsset(key, options) {
+  const config = getConfig();
+  return validatedPresign(config, key, options?.expiresIn);
+}
 async function deleteAsset(key) {
   const config = getConfig();
   const r2Url = buildR2Url(config, key);
@@ -1656,10 +1723,11 @@ export {
   configureAuth,
   configureStorage,
   uploadAsset,
+  presignAsset,
   deleteAsset,
   generate,
   configure,
   listModels,
   getModel
 };
-//# sourceMappingURL=chunk-RPORXMST.js.map
+//# sourceMappingURL=chunk-RC2KZLI2.js.map