@examplary/apps 0.0.1 → 1.0.0

package/README.md

@@ -31,7 +31,7 @@ app.addCapability(exportCapability);
 export default app;
 ```
 
-Hooks can read secrets set with `exp app set-secret NAME value`, which are never sent to the
+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`:
 
@@ -52,12 +52,13 @@ Capabilities add features to the platform, each with hooks of its own:
 - `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.
 
-`app.addQuestionType(Essay)` adds a question type, defined with `defineQuestionType()`. Its
+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. Workspaces that install the app get
-all of its question types.
+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.
@@ -70,6 +71,6 @@ 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 app upload` evaluates `app.ts`, bundles every component for the browser
+`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,7 +1,7 @@
 {
   "name": "@examplary/apps",
   "packageManager": "yarn@4.8.1",
-  "version": "0.0.1",
+  "version": "1.0.0",
   "description": "Define Examplary apps and question types in TypeScript.",
   "scripts": {
     "release": "semantic-release -e semantic-release-monorepo"
@@ -16,5 +16,10 @@
   "types": "./src/index.ts",
   "dependencies": {
     "@examplary/schemas": "*"
+  },
+  "homepage": "https://examplary.ai/developers",
+  "author": {
+    "name": "Examplary AI",
+    "email": "hi@examplary.ai"
   }
 }

package/src/app.ts

@@ -1,6 +1,5 @@
 import { Capability } from "./capabilities/Capability";
 import { resolveComponent, serializeField } from "./fields";
-import { AppQuestionType } from "./question-type";
 import {
   AppDefinition,
   FullAppDefinition,
@@ -41,7 +40,11 @@ class App {
 
   addCapability(capability: Capability) {
     const def = capability.toDefinition();
-    this.definition.capabilities.push(def.capability);
+    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);
@@ -65,13 +68,6 @@ class App {
     this.definition.settings.push(serializeField(settingDef));
   }
 
-  /** Adds a question type, see `defineQuestionType()`. */
-  addQuestionType(questionType: AppQuestionType) {
-    const { questionType: definition, hooks } = questionType.toDefinition();
-    this.definition.questionTypes.push(definition);
-    this.definition.hooks.push(...hooks);
-  }
-
   addSettingsValidateStep(
     fn: (settings: Record<string, any>) => Promise<boolean> | boolean,
   ) {

package/src/capabilities/Capability.ts

@@ -3,10 +3,13 @@ import {
   HookDefinition,
   ComponentDefinition,
   AssetDefinition,
+  QuestionTypeDefinition,
 } from "../types";
 
-export type ToCapabilityDefinition = {
-  capability: CapabilityDefinition;
+export type ToCapabilityDefinition = (
+  | { capability: CapabilityDefinition }
+  | { questionType: QuestionTypeDefinition }
+) & {
   hooks: HookDefinition[];
   components: ComponentDefinition[];
   assets: AssetDefinition[];

package/src/{question-type.ts → capabilities/QuestionType.ts}

@@ -1,14 +1,30 @@
-import type { Question } from "@examplary/schemas";
+import type { Question, SettingType } from "@examplary/schemas";
 
-import { HookDefinition, QuestionTypeDefinition } from "./types";
+import { Capability, ToCapabilityDefinition } from "./Capability";
+import { QuestionTypeDefinition } from "../types";
 
 export type QuestionValidation = { valid: boolean; error?: string };
 
-/** A question type of an app, see `defineQuestionType()`. */
-export class AppQuestionType {
+/**
+ * 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(private definition: QuestionTypeDefinition) {}
+  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
@@ -22,10 +38,7 @@ export class AppQuestionType {
     this.functions["validate-question"] = fn;
   }
 
-  toDefinition(): {
-    questionType: QuestionTypeDefinition & { hooks?: Record<string, string> };
-    hooks: HookDefinition[];
-  } {
+  toDefinition(): ToCapabilityDefinition {
     const hookId = (name: string) =>
       `question-types.${this.definition.id}.${name}`;
     const names = Object.keys(this.functions);
@@ -43,13 +56,8 @@ export class AppQuestionType {
         id: hookId(name),
         fn: this.functions[name],
       })),
+      components: [],
+      assets: [],
     };
   }
 }
-
-/**
- * A question type, to add with `app.addQuestionType()`. Its file paths are
- * relative to `app.ts`, e.g. `./essay/component-assessment.tsx`.
- */
-export const defineQuestionType = (questionType: QuestionTypeDefinition) =>
-  new AppQuestionType(questionType);

package/src/capabilities/index.ts

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

package/src/env.ts

@@ -4,7 +4,7 @@ declare global {
 }
 
 /**
- * Secrets set with `exp app set-secret`, available in the app's hooks. Values
+ * 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(

package/src/index.ts

@@ -2,7 +2,6 @@ export * from "./types";
 export type * from "./types";
 
 export * from "./app";
-export * from "./question-type";
 export * from "./capabilities";
 export * from "./context";
 export * from "./env";

package/src/types.ts

@@ -88,7 +88,7 @@ export type AssetDefinition = {
 type TranslatablePath = string | Record<string, string>;
 
 /**
- * A question type the app provides. Its `components`, `functions` and `icon`,
+ * 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<