@tribe-nest/forge 2.1.0 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "publishConfig": {
     "access": "public"
   },

package/src/server/jobs.ts

@@ -370,3 +370,90 @@ export async function aggregateAppCollection(
   if (!res.ok) throw new Error(`aggregateAppCollection ${slug} failed: ${res.status} ${await res.text().catch(() => "")}`);
   return res.json();
 }
+
+/**
+ * Upload a file and get back a hosted URL, in two steps.
+ *
+ * The two steps are not a formality. The bytes go to a STAGING key that does not
+ * survive: `finalizeAppUpload` moves the file to its real home, and anything
+ * never finalized is deleted within the hour. So the URL you can actually use is
+ * the one finalize returns — a staged URL will stop working, and the upload will
+ * not be counted against the profile's storage.
+ *
+ *   const up = await createAppUpload(ctx, cfg, "cover.png", bytes.byteLength)
+ *   await fetch(up.uploadUrl, { method: "PUT", headers: up.requiredHeaders, body: bytes })
+ *   const media = await finalizeAppUpload(ctx, cfg, up.uploadId)   // media.url is yours
+ *
+ * `size` is a hint so an over-quota upload fails before the transfer rather than
+ * after it; the size recorded is whatever storage reports once the bytes land.
+ * The file name decides the type, and script-capable types (html, svg) are
+ * refused.
+ */
+export async function createAppUpload(
+  ctx: JobContext,
+  cfg: AppJobsConfig,
+  fileName: string,
+  size?: number,
+): Promise<{
+  uploadId: string;
+  uploadUrl: string;
+  requiredHeaders: Record<string, string>;
+  method: "PUT";
+  expiresAt: string;
+}> {
+  const res = await fetch(`${cfg.apiUrl}/public/apps/${cfg.appId}/uploads`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-app-sync-token": ctx.token },
+    body: JSON.stringify({ fileName, size }),
+  });
+  if (!res.ok) throw new Error(`createAppUpload failed: ${res.status} ${await res.text().catch(() => "")}`);
+  return res.json();
+}
+
+/**
+ * Complete an upload started with {@link createAppUpload} and get the media row.
+ *
+ * Safe to retry — finalizing twice returns the same media rather than storing the
+ * file twice. Takes no size: the platform reads it back from storage.
+ */
+export async function finalizeAppUpload(
+  ctx: JobContext,
+  cfg: AppJobsConfig,
+  uploadId: string,
+): Promise<{ id: string; url: string; size: string; type: string; name: string }> {
+  const res = await fetch(`${cfg.apiUrl}/public/apps/${cfg.appId}/uploads/${uploadId}/finalize`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-app-sync-token": ctx.token },
+    body: "{}",
+  });
+  if (!res.ok) throw new Error(`finalizeAppUpload failed: ${res.status} ${await res.text().catch(() => "")}`);
+  return res.json();
+}
+
+/**
+ * Send an email as this app.
+ *
+ * The From resolves to the app's own sending identity when the owner configured
+ * one, otherwise the profile's — so mail is attributed to the creator, not to
+ * TribeNest, without the app holding any mail credentials.
+ *
+ *   await sendAppEmail(ctx, cfg, { to: user.email, subject: "Booked", html })
+ *
+ * Bounded on purpose: at most 50 recipients per call, and a daily per-app
+ * recipient budget, because the send is charged to the owner's allocation. For a
+ * campaign, use the platform's messaging tools instead — they handle consent and
+ * unsubscribes, which this deliberately does not.
+ */
+export async function sendAppEmail(
+  ctx: JobContext,
+  cfg: AppJobsConfig,
+  msg: { to: string | string[]; subject: string; html: string; replyTo?: string },
+): Promise<{ sent: number }> {
+  const res = await fetch(`${cfg.apiUrl}/public/apps/${cfg.appId}/emails`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-app-sync-token": ctx.token },
+    body: JSON.stringify(msg),
+  });
+  if (!res.ok) throw new Error(`sendAppEmail failed: ${res.status} ${await res.text().catch(() => "")}`);
+  return res.json();
+}