@examplary/apps 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,76 @@
-# Temporary Holding Version
+# @examplary/apps
 
-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.
+Types and helpers for writing an Examplary app in TypeScript. An app is an `app.ts` (or
+`app.js`) that default-exports `defineApp()`, with settings, capabilities and hooks added to
+it. Files are referenced by paths relative to the app's directory.
+
+```ts
+// app.ts
+import { defineApp, InstallationScope } from "@examplary/apps";
+
+import exportCapability from "./capabilities/export";
+
+const app = defineApp({
+  id: "my-org.my-app",
+  name: { en: "My app" },
+  description: { en: "Sends tests to my platform" },
+  icon: "./icon.svg",
+  scope: InstallationScope.Org,
+});
+
+app.addSetting({
+  key: "apiToken",
+  label: { en: "API token" },
+  type: "password",
+  secret: true,
+  schema: { type: "string", minLength: 10 },
+});
+
+app.addCapability(exportCapability);
+
+export default app;
+```
+
+Hooks can read secrets set with `exp set-secret NAME value`, which are never sent to the
+dashboard. Read them inside a hook, not at the top of a module; a missing secret is
+`undefined`:
+
+```ts
+import { env } from "@examplary/apps";
+
+const clientSecret = env.GOOGLE_CLIENT_SECRET;
+```
+
+Hooks run in a sandbox with standard JavaScript, `fetch`, `Headers`, `Response`, `URL`,
+`URLSearchParams`, `TextEncoder`, `crypto.randomUUID()` and `crypto.subtle.digest()`: no Node APIs, and no npm packages that need them.
+`context.org` and `context.user` say who a hook runs for.
+
+Capabilities add features to the platform, each with hooks of its own:
+
+- `ExportOption` — a "Send to…" entry in the exam export menus.
+- `SettingsButton` — a button on the app's card in the workspace's settings, e.g. "Sync now".
+- `ResultsDestination` — somewhere teachers publish grades to, like a gradebook.
+- `AssessmentPrerequisite` — something a student has to meet before starting a test, like a
+  secure browser, with a settings component for the exam's settings and a player component.
+- `QuestionType` — a question type, which workspaces that install the app can use in tests.
+
+A `new QuestionType({...})` takes the question type's definition. Its
+`components`, `icon`, `readme` and `previewImage` are paths relative to `app.ts`, e.g.
+`./essay/component-assessment.tsx`. `Essay.addValidator(({ question }) => ({ valid, error }))`
+checks questions of that type, e.g. generated ones, as a hook. `Essay.addSetting({...})` adds a
+setting after those in the definition's `settings`.
+
+`app.addSettingsPrepareStep()`, `app.addSettingsValidateStep()` and `app.addUninstallStep()`
+hook into saving the app's settings and removing it from a workspace.
+
+A setting's `type` already checks its value (a non-empty string, a URL, a boolean, one of a
+select's options); a `schema` adds a JSON schema for anything else, and `optional: true` lets it
+be left empty. A zod (v4) schema works too, but adds about 450 kB to the server bundle, which
+every hook call loads.
+
+A `component` setting renders a React component (a `.tsx` file that default-exports a
+`FrontendSettingsFieldComponent` from `@examplary/ui`), which calls `setValue()` and `submit()`.
+
+`npx @examplary/cli publish` evaluates `app.ts`, bundles every component for the browser
+and the app itself for the server, uploads the assets and publishes the result. See
+[docs/apps.md](../../docs/apps.md) for how the platform handles apps.

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "@examplary/apps",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "packageManager": "yarn@4.8.1",
+  "version": "1.0.0",
+  "description": "Define Examplary apps and question types in TypeScript.",
+  "scripts": {
+    "release": "semantic-release -e semantic-release-monorepo"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "dependencies": {
+    "@examplary/schemas": "*"
+  },
+  "homepage": "https://examplary.ai/developers",
+  "author": {
+    "name": "Examplary AI",
+    "email": "hi@examplary.ai"
+  }
+}

package/src/app.ts

@@ -0,0 +1,100 @@
+import { Capability } from "./capabilities/Capability";
+import { resolveComponent, serializeField } from "./fields";
+import {
+  AppDefinition,
+  FullAppDefinition,
+  HookInput,
+  SettingsField,
+} from "./types";
+
+class App {
+  protected definition: FullAppDefinition;
+
+  constructor(definition: AppDefinition) {
+    this.definition = {
+      settings: [],
+      hooks: [],
+      components: [],
+      assets: [],
+      capabilities: [],
+      questionTypes: [],
+      ...definition,
+    };
+  }
+
+  toDefinition(): FullAppDefinition {
+    return this.definition;
+  }
+
+  /** Runs one of the app's hooks; the platform calls this in the sandbox. */
+  async runHook({ hook, args, env, context }: HookInput) {
+    globalThis.__examplaryEnv = env;
+    globalThis.__examplaryContext = context;
+
+    const definition = this.definition.hooks.find(({ id }) => id === hook);
+    if (!definition) {
+      throw new Error(`The app has no hook "${hook}"`);
+    }
+    return definition.fn(...args);
+  }
+
+  addCapability(capability: Capability) {
+    const def = capability.toDefinition();
+    if ("questionType" in def) {
+      this.definition.questionTypes.push(def.questionType);
+    } else {
+      this.definition.capabilities.push(def.capability);
+    }
+    this.definition.assets.push(...def.assets);
+    this.definition.hooks.push(...def.hooks);
+    this.definition.components.push(...def.components);
+  }
+
+  addSetting(setting: SettingsField) {
+    const settingDef = { ...setting };
+    if (settingDef.type === "component") {
+      if (!settingDef.component) {
+        throw new Error(
+          `Needs a component set when type = component for setting "${setting.key}"`,
+        );
+      }
+      const id = `settings.${setting.key}.component`;
+      this.definition.components.push({
+        id,
+        ...resolveComponent(setting.component!),
+      });
+      settingDef.component = id;
+    }
+    this.definition.settings.push(serializeField(settingDef));
+  }
+
+  addSettingsValidateStep(
+    fn: (settings: Record<string, any>) => Promise<boolean> | boolean,
+  ) {
+    this.definition.hooks.push({
+      id: "settings.validate",
+      fn,
+    });
+  }
+
+  /** Runs when a workspace removes the app, e.g. to clean up elsewhere; throwing keeps it installed. */
+  addUninstallStep(
+    fn: (settings: Record<string, any>) => Promise<void> | void,
+  ) {
+    this.definition.hooks.push({ id: "uninstall", fn });
+  }
+
+  addSettingsPrepareStep(
+    fn: (
+      settings: Record<string, any>,
+    ) => Promise<Record<string, any>> | Record<string, any>,
+  ) {
+    this.definition.hooks.push({
+      id: "settings.prepare",
+      fn,
+    });
+  }
+}
+
+export const defineApp = <T extends AppDefinition>(definition: T): App =>
+  new App(definition);

package/src/capabilities/AssessmentPrerequisite.ts

@@ -0,0 +1,215 @@
+import { TranslatableType } from "@examplary/schemas";
+
+import { Capability, ToCapabilityDefinition } from "./Capability";
+import { resolveComponent, serializeField } from "../fields";
+import { ComponentInput, SettingsField } from "../types";
+
+/** The exam a prerequisite applies to, as its hooks see it. */
+export type PrerequisiteExam = {
+  id: string;
+  name: string;
+  published: boolean;
+  startDateTime?: string;
+  endDateTime?: string;
+  /** Whether the browser's spell check may be used */
+  spellCheck: boolean;
+  /** Where students open the test, and where signed-in students take it */
+  publicUrl: string;
+  playerUrl: string;
+  /** The workspace's own dashboard URL and domain */
+  orgUrl: string;
+  orgDomain: string;
+};
+
+/** The student's request, with only the headers the prerequisite asked for. */
+export type PrerequisiteRequest = {
+  method: string;
+  path: string;
+  host: string;
+  headers: Record<string, string>;
+};
+
+export type PrerequisiteUser = {
+  id: string;
+  name?: string;
+  firstName?: string;
+  lastName?: string;
+  email?: string;
+  /** Signs the student in and opens the test, valid for an hour */
+  signInUrl: string;
+};
+
+export type PrerequisiteFile = {
+  contentType: string;
+  filename?: string;
+  body: string;
+};
+
+type Check = {
+  exam: PrerequisiteExam;
+  /** The values of the prerequisite's `examSettings` for this exam */
+  examSettings: Record<string, any>;
+  /** What `onExamUpdated` stored for this exam */
+  data: Record<string, any>;
+};
+
+type Settings = Record<string, any>;
+
+type PrerequisiteFunction = {
+  /** Who may call it: editors of the exam (e.g. from the settings component), or its students */
+  for: "editor" | "student";
+  run: (
+    settings: Settings,
+    call: Check & { user?: PrerequisiteUser; input?: unknown },
+  ) => unknown;
+};
+
+type AssessmentPrerequisiteDefinition = {
+  id: string;
+
+  /** The label of the switch that turns it on in the exam settings */
+  name: TranslatableType;
+
+  /** Shown in the exam settings once it's turned on */
+  description?: TranslatableType;
+
+  /** The plans the switch is available on, all when left out */
+  requiredPlans?: string[];
+
+  /** Settings per exam, shown below the switch once it's turned on */
+  examSettings?: Omit<SettingsField, "scope" | "component">[];
+
+  /** The request headers the hooks get, e.g. a signature the secure browser adds */
+  requestHeaders?: string[];
+
+  /** Whether the test's completed and timed-out screens offer a button to close the secure browser */
+  exitButton?: boolean;
+
+  /** Shown in the exam settings once it's turned on, e.g. links to the other side */
+  settingsComponent?: ComponentInput;
+
+  /** Shown to students while the prerequisite isn't met, e.g. how to open the secure browser */
+  playerComponent?: ComponentInput;
+
+  /**
+   * Whether a student may start a session. `input` is what the player
+   * component passed with `setValue()`. Met when left out.
+   */
+  isMet?: (
+    settings: Settings,
+    check: Check & { request: PrerequisiteRequest; input?: string },
+  ) => boolean | Promise<boolean>;
+
+  /** Runs on every request within a session; throw to refuse it, with a message for the student */
+  validateRequest?: (
+    settings: Settings,
+    check: Check & { request: PrerequisiteRequest },
+  ) => void | Promise<void>;
+
+  /**
+   * Runs when the exam is saved while the prerequisite is turned on, or has
+   * data from before. What it returns is stored as the exam's `data`.
+   */
+  onExamUpdated?: (
+    settings: Settings,
+    update: Check & { enabled: boolean },
+  ) => Settings | void | Promise<Settings | void>;
+
+  /** Server-side functions the components can call */
+  functions?: Record<string, PrerequisiteFunction>;
+
+  /** Files served publicly by name, e.g. a configuration the secure browser downloads */
+  files?: Record<
+    string,
+    (
+      settings: Settings,
+      check: Check,
+    ) => PrerequisiteFile | Promise<PrerequisiteFile>
+  >;
+};
+
+/** Something students must meet to take a test, like using a secure browser. */
+export class AssessmentPrerequisite extends Capability {
+  protected definition: AssessmentPrerequisiteDefinition;
+
+  constructor(definition: AssessmentPrerequisiteDefinition) {
+    super();
+    this.definition = definition;
+  }
+
+  toDefinition(): ToCapabilityDefinition {
+    const {
+      id,
+      settingsComponent,
+      playerComponent,
+      isMet,
+      validateRequest,
+      onExamUpdated,
+      functions = {},
+      files = {},
+      examSettings = [],
+      ...rest
+    } = this.definition;
+    const prefix = `capabilities.assessment-prerequisite.${id}`;
+    const def: ToCapabilityDefinition = {
+      capability: {
+        ...rest,
+        type: "assessment-prerequisite",
+        id,
+        examSettings: examSettings.map(serializeField),
+      },
+      hooks: [],
+      components: [],
+      assets: [],
+    };
+
+    const addHook = (name: string, fn: Function) => {
+      def.hooks.push({ id: `${prefix}.${name}`, fn });
+      return `${prefix}.${name}`;
+    };
+    const addComponent = (name: string, component: ComponentInput) => {
+      def.components.push({
+        id: `${prefix}.${name}`,
+        ...resolveComponent(component),
+      });
+      return `${prefix}.${name}`;
+    };
+
+    if (settingsComponent) {
+      def.capability.settingsComponent = addComponent(
+        "settings-component",
+        settingsComponent,
+      );
+    }
+    if (playerComponent) {
+      def.capability.playerComponent = addComponent(
+        "player-component",
+        playerComponent,
+      );
+    }
+    if (isMet) def.capability.isMet = addHook("is-met", isMet);
+    if (validateRequest) {
+      def.capability.validateRequest = addHook(
+        "validate-request",
+        validateRequest,
+      );
+    }
+    if (onExamUpdated) {
+      def.capability.onExamUpdated = addHook("on-exam-updated", onExamUpdated);
+    }
+    def.capability.functions = Object.fromEntries(
+      Object.entries(functions).map(([name, fn]) => [
+        name,
+        { for: fn.for, run: addHook(`functions.${name}`, fn.run) },
+      ]),
+    );
+    def.capability.files = Object.fromEntries(
+      Object.entries(files).map(([name, fn]) => [
+        name,
+        addHook(`files.${name}`, fn),
+      ]),
+    );
+
+    return def;
+  }
+}

package/src/capabilities/Capability.ts

@@ -0,0 +1,20 @@
+import {
+  CapabilityDefinition,
+  HookDefinition,
+  ComponentDefinition,
+  AssetDefinition,
+  QuestionTypeDefinition,
+} from "../types";
+
+export type ToCapabilityDefinition = (
+  | { capability: CapabilityDefinition }
+  | { questionType: QuestionTypeDefinition }
+) & {
+  hooks: HookDefinition[];
+  components: ComponentDefinition[];
+  assets: AssetDefinition[];
+};
+
+export abstract class Capability {
+  abstract toDefinition(): ToCapabilityDefinition;
+}

package/src/capabilities/ExportOption.ts

@@ -0,0 +1,136 @@
+import { TranslatableType } from "@examplary/schemas";
+
+import { Capability, ToCapabilityDefinition } from "./Capability";
+import { serializeField } from "../fields";
+import { CapabilityDefinition, SettingsField } from "../types";
+
+export enum ExportStatus {
+  inProgress = "inProgress",
+  completed = "completed",
+  failed = "failed",
+}
+
+export type ExportData<T> = {
+  status: ExportStatus;
+  resultUrl?: string;
+  /** What went wrong, shown to the user, e.g. the items the other side refused. */
+  message?: string;
+  data: T;
+};
+
+export enum ExportResourceType {
+  Exam = "Exam",
+  PracticeSpace = "PracticeSpace",
+}
+
+export enum ExportFormat {
+  /** A QTI 2.1 package, without Examplary-specific metadata and interactions */
+  Qti21 = "qti21",
+}
+
+/** What `startExport` gets to export: the platform prepares the formats the option asks for. */
+export type ExportResource = {
+  id: string;
+  name: string;
+  /** Where students open the test */
+  publicUrl: string;
+  /** Points to earn, or null when the test doesn't show points */
+  totalPoints: number | null;
+  /** Short-lived download URLs of the requested formats */
+  files: Partial<Record<ExportFormat, { url: string; filename: string }>>;
+};
+
+type ExportOptionSettingsField = Omit<SettingsField, "scope">;
+
+type ExportOptionDefinition = {
+  id: string;
+  name: TranslatableType;
+
+  /** The icon to be displayed for the export action */
+  icon: string;
+
+  /** The types of resources that this integration can export */
+  resourceTypes: ExportResourceType[];
+
+  /** Files the platform should prepare for `startExport`, e.g. a QTI package */
+  formats?: ExportFormat[];
+
+  /** Interval in milliseconds at which the export status should be checked */
+  statusCheckInterval?: number;
+
+  /** Get options to be displayed to the user in the 'Send to...' UI */
+  getExportOptions?: (
+    settings: Record<string, any>,
+  ) => ExportOptionSettingsField[] | Promise<ExportOptionSettingsField[]>;
+
+  /** Called to initiate an export of the given resource with the specified settings */
+  startExport: (
+    settings: Record<string, any>,
+    resource: ExportResource,
+  ) => ExportData<any> | Promise<ExportData<any>>;
+
+  /** Get an updated export status. By default this immediately returns the current export data */
+  getExportStatus?: (
+    _settings: Record<string, any>,
+    exportData: ExportData<any>,
+  ) => Promise<ExportData<any>>;
+};
+
+export class ExportOption extends Capability {
+  protected definition: CapabilityDefinition;
+
+  constructor(definition: ExportOptionDefinition) {
+    super();
+    this.definition = {
+      type: "export-option",
+      statusCheckInterval: 1000,
+      ...definition,
+    };
+  }
+
+  toDefinition() {
+    const prefix = `capabilities.export-exam-option.${this.definition.id}`;
+    const def: ToCapabilityDefinition = {
+      capability: { ...this.definition },
+      hooks: [],
+      components: [],
+      assets: [],
+    };
+
+    const input = this.definition as any as ExportOptionDefinition;
+
+    if (input.icon) {
+      def.assets.push({
+        id: `${prefix}.icon`,
+        path: input.icon,
+      });
+      def.capability.icon = `${prefix}.icon`;
+    }
+
+    if (input.getExportOptions) {
+      const getExportOptions = input.getExportOptions;
+      def.hooks.push({
+        id: `${prefix}.get-export-options`,
+        fn: async (settings: Record<string, any>) =>
+          (await getExportOptions(settings)).map(serializeField),
+      });
+      def.capability.getExportOptions = `${prefix}.get-export-options`;
+    }
+    if (input.startExport) {
+      def.hooks.push({
+        id: `${prefix}.start-export`,
+        fn: input.startExport,
+      });
+      def.capability.startExport = `${prefix}.start-export`;
+    }
+    if (input.getExportStatus) {
+      def.hooks.push({
+        id: `${prefix}.get-export-status`,
+        fn: input.getExportStatus,
+      });
+      def.capability.getExportStatus = `${prefix}.get-export-status`;
+    }
+
+    return def;
+  }
+}

package/src/capabilities/QuestionType.ts

@@ -0,0 +1,63 @@
+import type { Question, SettingType } from "@examplary/schemas";
+
+import { Capability, ToCapabilityDefinition } from "./Capability";
+import { QuestionTypeDefinition } from "../types";
+
+export type QuestionValidation = { valid: boolean; error?: string };
+
+/**
+ * A question type the app adds to Examplary. Its file paths are relative to
+ * `app.ts`, e.g. `./essay/component-assessment.tsx`.
+ */
+export class QuestionType extends Capability {
+  protected definition: QuestionTypeDefinition;
+  private functions: Record<string, Function> = {};
+
+  constructor(definition: QuestionTypeDefinition) {
+    super();
+    this.definition = definition;
+  }
+
+  /** Adds a setting teachers fill in for a question of this type, after those in its definition. */
+  addSetting(setting: SettingType) {
+    this.definition = {
+      ...this.definition,
+      settings: [...(this.definition.settings ?? []), setting],
+    };
+  }
+
+  /**
+   * Checks a question of this type, e.g. one AI generated, which is tried
+   * again with the `error` when it isn't valid. Runs on the server, as a hook.
+   */
+  addValidator(
+    fn: (input: {
+      question: Question;
+    }) => QuestionValidation | Promise<QuestionValidation>,
+  ) {
+    this.functions["validate-question"] = fn;
+  }
+
+  toDefinition(): ToCapabilityDefinition {
+    const hookId = (name: string) =>
+      `question-types.${this.definition.id}.${name}`;
+    const names = Object.keys(this.functions);
+
+    return {
+      questionType: names.length
+        ? {
+            ...this.definition,
+            hooks: Object.fromEntries(
+              names.map((name) => [name, hookId(name)]),
+            ),
+          }
+        : this.definition,
+      hooks: names.map((name) => ({
+        id: hookId(name),
+        fn: this.functions[name],
+      })),
+      components: [],
+      assets: [],
+    };
+  }
+}

package/src/capabilities/ResultsDestination.ts

@@ -0,0 +1,71 @@
+import { TranslatableType } from "@examplary/schemas";
+
+import { Capability, ToCapabilityDefinition } from "./Capability";
+
+/** An exam's new and changed grades, of students synced from a student information system. */
+export type ResultsToPublish = {
+  exam: { id: string; name: string; takenAt: string };
+  /** The publishing teacher's LAS key, as the SIS sync stored it */
+  teacherLasKey?: string;
+  students: {
+    /** With the exam ID, identifies the grade, so publishing again updates it */
+    studentId: string;
+    externalId: string;
+    points: number;
+    maxPoints: number;
+    result: { type: "Grade0.0-10.0" | "PassOrFail" | "OVG"; value: string };
+    createdAt: string;
+    updatedAt: string;
+  }[];
+};
+
+export type PublishResultsOutcome = {
+  accepted: boolean;
+  /** Why the results weren't accepted, shown to the teacher */
+  message?: string;
+  /** What the other side answered, kept in the audit log */
+  response?: unknown;
+};
+
+type ResultsDestinationDefinition = {
+  id: string;
+
+  /** Where the results go, as teachers know it, e.g. "Magister" */
+  name: TranslatableType;
+
+  /** Settings that have to be filled in for teachers to be offered this destination */
+  requiresSettings?: string[];
+
+  publishResults: (
+    settings: Record<string, any>,
+    results: ResultsToPublish,
+  ) => PublishResultsOutcome | Promise<PublishResultsOutcome>;
+};
+
+/** Somewhere teachers can publish an exam's grades to from the publish results dialog, e.g. a gradebook. */
+export class ResultsDestination extends Capability {
+  protected definition: ResultsDestinationDefinition;
+
+  constructor(definition: ResultsDestinationDefinition) {
+    super();
+    this.definition = definition;
+  }
+
+  toDefinition(): ToCapabilityDefinition {
+    const { id, name, requiresSettings = [], publishResults } = this.definition;
+    const hook = `capabilities.results-destination.${id}.publish-results`;
+
+    return {
+      capability: {
+        type: "results-destination",
+        id,
+        name,
+        requiresSettings,
+        publishResults: hook,
+      },
+      hooks: [{ id: hook, fn: publishResults }],
+      components: [],
+      assets: [],
+    };
+  }
+}

package/src/capabilities/SettingsButton.ts

@@ -0,0 +1,35 @@
+import { TranslatableType } from "@examplary/schemas";
+
+import { Capability, ToCapabilityDefinition } from "./Capability";
+
+type SettingsButtonDefinition = {
+  id: string;
+
+  /** The label of the button on the app's card */
+  label: TranslatableType;
+
+  /** Runs when an admin clicks the button; the message of an error thrown here is shown to them */
+  run: (settings: Record<string, any>) => Promise<void> | void;
+};
+
+/** A button on the app's card in the workspace's settings, e.g. "Sync now". */
+export class SettingsButton extends Capability {
+  protected definition: SettingsButtonDefinition;
+
+  constructor(definition: SettingsButtonDefinition) {
+    super();
+    this.definition = definition;
+  }
+
+  toDefinition(): ToCapabilityDefinition {
+    const { id, label, run } = this.definition;
+    const hook = `capabilities.settings-button.${id}.run`;
+
+    return {
+      capability: { type: "settings-button", id, label, run: hook },
+      hooks: [{ id: hook, fn: run }],
+      components: [],
+      assets: [],
+    };
+  }
+}

package/src/capabilities/index.ts

@@ -0,0 +1,6 @@
+export * from "./AssessmentPrerequisite";
+export * from "./Capability";
+export * from "./ExportOption";
+export * from "./QuestionType";
+export * from "./ResultsDestination";
+export * from "./SettingsButton";

package/src/context.ts

@@ -0,0 +1,16 @@
+import { HookContext } from "./types";
+
+declare global {
+  /** Who a hook runs for, provided by the platform when it runs a hook. */
+  var __examplaryContext: HookContext | undefined;
+}
+
+/** Who the running hook is for: the workspace, and the user when there is one. */
+export const context: HookContext = {
+  get org() {
+    return globalThis.__examplaryContext?.org as string;
+  },
+  get user() {
+    return globalThis.__examplaryContext?.user;
+  },
+};

package/src/env.ts

@@ -0,0 +1,13 @@
+declare global {
+  /** The app's environment, provided by the platform when it runs a hook. */
+  var __examplaryEnv: Record<string, string> | undefined;
+}
+
+/**
+ * Secrets set with `exp set-secret`, available in the app's hooks. Values
+ * are read when accessed, so read them inside a hook, not at the top of a module.
+ */
+export const env: Record<string, string | undefined> = new Proxy(
+  {},
+  { get: (_, name) => globalThis.__examplaryEnv?.[name as string] },
+);

package/src/fields.ts

@@ -0,0 +1,28 @@
+import { ComponentInput, JsonSchema, ZodSchema } from "./types";
+
+const isZodSchema = (schema: JsonSchema | ZodSchema): schema is ZodSchema =>
+  typeof schema.toJSONSchema === "function";
+
+/**
+ * A settings field with its JSON schema as text, so it can be stored and sent
+ * around as is (DynamoDB would turn an empty string in it into null). A zod
+ * schema is converted, and tells whether the field is optional.
+ */
+export const serializeField = <T extends Record<string, any>>({
+  schema,
+  ...field
+}: T) => {
+  if (!schema) return field;
+  if (!isZodSchema(schema)) {
+    return { ...field, schema: JSON.stringify(schema) };
+  }
+  return {
+    ...field,
+    schema: JSON.stringify(schema.toJSONSchema()),
+    optional: field.optional ?? schema.safeParse(undefined).success,
+  };
+};
+
+/** A component given by its path, as a component definition without an ID. */
+export const resolveComponent = (component: ComponentInput) =>
+  typeof component === "string" ? { path: component } : component;

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from "./types";
+export type * from "./types";
+
+export * from "./app";
+export * from "./capabilities";
+export * from "./context";
+export * from "./env";

package/src/types.ts

@@ -0,0 +1,122 @@
+import {
+  App,
+  AppCapabilityType,
+  AppSettingsFieldType,
+  QuestionType,
+} from "@examplary/schemas";
+
+/** What the platform passes to `App.runHook()` when it calls a hook. */
+/** Who a hook runs for, see `context`. */
+export type HookContext = {
+  /** The ID of the workspace */
+  org: string;
+  /** The ID of the user, when a user started it */
+  user?: string;
+};
+
+export type HookInput = {
+  hook: string;
+  args: unknown[];
+  env: Record<string, string>;
+  context: HookContext;
+};
+
+/** App definition */
+export type AppDefinition = Omit<
+  App,
+  | "settings"
+  | "capabilities"
+  | "hooks"
+  | "components"
+  | "assets"
+  | "questionTypes"
+>;
+
+/** Installation scope */
+export enum InstallationScope {
+  User = "user",
+  Org = "org",
+}
+
+export type ComponentInput =
+  | string
+  | {
+      path: string;
+      translations?: Record<string, Record<string, string>>;
+    };
+
+/** A JSON schema, e.g. `{ type: "string", pattern: "^woots_" }` */
+export type JsonSchema = Record<string, unknown>;
+
+/** A zod (v4) schema, without depending on zod */
+export type ZodSchema = {
+  toJSONSchema: () => unknown;
+  safeParse: (value: unknown) => { success: boolean };
+};
+
+export type SettingsField = Omit<
+  AppSettingsFieldType,
+  "component" | "schema"
+> & {
+  component?: ComponentInput;
+  /**
+   * What the value has to match, when its `type` alone isn't enough. A JSON
+   * schema keeps the app's server bundle small; zod adds about 450 kB to it.
+   */
+  schema?: JsonSchema | ZodSchema;
+};
+
+export type CapabilityDefinition = AppCapabilityType;
+
+export type HookDefinition = {
+  id: string;
+  fn: Function;
+};
+
+export type ComponentDefinition = {
+  id: string;
+  path: string;
+  translations?: Record<string, Record<string, string>>;
+};
+
+export type AssetDefinition = {
+  id: string;
+  path: string;
+};
+
+/** A file path relative to `app.ts`, or one per language code. */
+type TranslatablePath = string | Record<string, string>;
+
+/**
+ * A question type the app provides. Its `components` and `icon`,
+ * and its `readme` and `previewImage`, are paths relative to `app.ts`.
+ */
+export type QuestionTypeDefinition = Omit<
+  QuestionType,
+  | "readme"
+  | "readmeUrls"
+  | "previewImage"
+  | "previewImageUrls"
+  | "previewData"
+  | "stylesheet"
+> & {
+  readme?: TranslatablePath;
+  previewImage?: TranslatablePath;
+};
+
+export type FullAppDefinition = Omit<
+  App,
+  | "settings"
+  | "hooks"
+  | "components"
+  | "assets"
+  | "capabilities"
+  | "questionTypes"
+> & {
+  settings: SettingsField[];
+  hooks: HookDefinition[];
+  components: ComponentDefinition[];
+  assets: AssetDefinition[];
+  capabilities: AppCapabilityType[];
+  questionTypes: QuestionTypeDefinition[];
+};