npm - @pylonsync/sdk - Versions diffs - 0.11.0 → 0.11.1 - Mend

@pylonsync/sdk 0.11.0 → 0.11.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/dist/index.d.ts CHANGED Viewed

@@ -666,6 +666,17 @@ export interface AppManifest {
     /** Self-hosted web fonts. Fetched + self-hosted at build; preload +
      *  `@font-face` auto-injected into the SSR `<head>`. */
     fonts?: ManifestFont[];
+    /** Environment variables this app cannot run correctly without.
+     *  `pylon deploy` refuses to ship when one is missing from the
+     *  project's secrets. */
+    requiredEnv?: ManifestRequiredEnv[];
+}
+/** One environment variable the app declares it needs. */
+export interface ManifestRequiredEnv {
+    name: string;
+    /** What breaks without it. Printed by `pylon deploy` when it is missing,
+     *  so write the consequence, not the category. */
+    description: string;
 }
 /**
  * Declare a recurring job. Runs the named function every time the cron
@@ -1084,12 +1095,40 @@ export declare function buildManifest(options: {
     connections?: ManifestConnection[];
     crons?: ManifestCron[];
     fonts?: ManifestFont[];
+    /** Environment variables this app cannot run correctly without. Declare
+     *  the ones whose absence is silent — a public origin baked into a script,
+     *  a webhook secret, an API base URL. `pylon deploy` checks them against
+     *  the project's secrets and refuses to ship when one is missing.
+     *
+     *  ```ts
+     *  requiredEnv: [
+     *    requireEnv("SITE_URL", "this app's public origin; baked into /widget.js"),
+     *  ]
+     *  ```
+     */
+    requiredEnv?: ManifestRequiredEnv[];
     /** Set by `discoverFunctions()` (spread its result into this call).
      *  When true, the framework's AgentRun/AgentMessage entities and
      *  their owner-scoping policies are appended to the manifest —
      *  unless the app already declares entities with those names. */
     hasAgents?: boolean;
 }): AppManifest;
+/**
+ * Declare an environment variable the app cannot run correctly without.
+ *
+ * This exists for the failures that are invisible. A missing database URL
+ * crashes on the first query and someone notices in a minute; a missing
+ * public origin gets baked into a script tag, served to a customer's
+ * website, and nothing errors anywhere — the data just never arrives.
+ *
+ * `pylon deploy` reads these off the manifest, compares them against the
+ * project's secrets, and refuses to ship when one is missing.
+ *
+ * Write the consequence in `description`, not the category: "the public
+ * origin baked into /widget.js" tells the person reading the failure what
+ * breaks, and "site URL" does not.
+ */
+export declare function requireEnv(name: string, description: string): ManifestRequiredEnv;
 export { defineStudioConfig, defineStudioExtensions, type BrandConfig, type ThemeConfig, type ThemeAccent, type ThemeAppearance, type IconName, type SidebarConfig, type SidebarSection, type SidebarItem, type SidebarPageItem, type SidebarResourceItem, type SidebarLinkItem, type SidebarHeadingItem, type SidebarFooter, type SidebarFooterCard, type SidebarFooterCustom, type ResourceConfig, type ResourceListConfig, type ColumnConfig, type ColumnRenderer, type RendererKind, type RendererText, type RendererAvatar, type RendererBadge, type RendererDate, type RendererLink, type RendererBoolean, type RendererNumber, type RendererJson, type RendererCustom, type BulkAction, type RowAction, type PageConfig, type StudioConfig, type StudioCellRendererProps, type StudioPageProps, type StudioExtensions, } from "./studio";
 /**
  * Behavior — a function that mutates the entity definition before it's

package/package.json CHANGED Viewed

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.11.0",
+  "version": "0.11.1",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",

package/src/index.ts CHANGED Viewed

@@ -854,6 +854,18 @@ export interface AppManifest {
   /** Self-hosted web fonts. Fetched + self-hosted at build; preload +
    *  `@font-face` auto-injected into the SSR `<head>`. */
   fonts?: ManifestFont[];
+  /** Environment variables this app cannot run correctly without.
+   *  `pylon deploy` refuses to ship when one is missing from the
+   *  project's secrets. */
+  requiredEnv?: ManifestRequiredEnv[];
+}
+/** One environment variable the app declares it needs. */
+export interface ManifestRequiredEnv {
+  name: string;
+  /** What breaks without it. Printed by `pylon deploy` when it is missing,
+   *  so write the consequence, not the category. */
+  description: string;
 }
 /**
@@ -2099,6 +2111,18 @@ export function buildManifest(options: {
   connections?: ManifestConnection[];
   crons?: ManifestCron[];
   fonts?: ManifestFont[];
+  /** Environment variables this app cannot run correctly without. Declare
+   *  the ones whose absence is silent — a public origin baked into a script,
+   *  a webhook secret, an API base URL. `pylon deploy` checks them against
+   *  the project's secrets and refuses to ship when one is missing.
+   *
+   *  ```ts
+   *  requiredEnv: [
+   *    requireEnv("SITE_URL", "this app's public origin; baked into /widget.js"),
+   *  ]
+   *  ```
+   */
+  requiredEnv?: ManifestRequiredEnv[];
   /** Set by `discoverFunctions()` (spread its result into this call).
    *  When true, the framework's AgentRun/AgentMessage entities and
    *  their owner-scoping policies are appended to the manifest —
@@ -2179,9 +2203,34 @@ export function buildManifest(options: {
     ...(options.fonts && options.fonts.length > 0
       ? { fonts: options.fonts }
       : {}),
+    ...(options.requiredEnv && options.requiredEnv.length > 0
+      ? { requiredEnv: options.requiredEnv }
+      : {}),
   };
 }
+/**
+ * Declare an environment variable the app cannot run correctly without.
+ *
+ * This exists for the failures that are invisible. A missing database URL
+ * crashes on the first query and someone notices in a minute; a missing
+ * public origin gets baked into a script tag, served to a customer's
+ * website, and nothing errors anywhere — the data just never arrives.
+ *
+ * `pylon deploy` reads these off the manifest, compares them against the
+ * project's secrets, and refuses to ship when one is missing.
+ *
+ * Write the consequence in `description`, not the category: "the public
+ * origin baked into /widget.js" tells the person reading the failure what
+ * breaks, and "site URL" does not.
+ */
+export function requireEnv(
+  name: string,
+  description: string,
+): ManifestRequiredEnv {
+  return { name, description };
+}
 // ---------------------------------------------------------------------------
 // Studio configuration — re-exports
 // ---------------------------------------------------------------------------

package/src/sdk.types.test.ts CHANGED Viewed

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { auth, buildManifest, entity, field } from "./index";
+import { auth, buildManifest, entity, field, requireEnv } from "./index";
 /**
  * The shape callers actually hit.
@@ -109,3 +109,35 @@ describe("auth() account deletion hook", () => {
     expect("on_delete_account" in auth({})).toBe(false);
   });
 });
+// ---------------------------------------------------------------------------
+// requiredEnv
+// ---------------------------------------------------------------------------
+test("requiredEnv only appears in the manifest when something is declared", () => {
+  const bare = buildManifest({
+    name: "app",
+    version: "1.0.0",
+    entities: [],
+    routes: [],
+  });
+  // An empty key in every manifest is noise the Rust side then has to ignore.
+  expect("requiredEnv" in bare).toBe(false);
+  const declared = buildManifest({
+    name: "app",
+    version: "1.0.0",
+    entities: [],
+    routes: [],
+    requiredEnv: [requireEnv("SITE_URL", "the public origin")],
+  });
+  expect(declared.requiredEnv).toEqual([
+    { name: "SITE_URL", description: "the public origin" },
+  ]);
+});
+test("requireEnv keeps the description, because that is what the failure prints", () => {
+  const v = requireEnv("STRIPE_WEBHOOK_SECRET", "payments post here and are dropped without it");
+  expect(v.name).toBe("STRIPE_WEBHOOK_SECRET");
+  expect(v.description).toContain("dropped");
+});