@domino-sdk/relay 1.0.0-next.5 → 1.0.0-next.7

package/README.md

@@ -6,6 +6,18 @@ Author quests and connect an application to Domino Relay.
 pnpm add @domino-sdk/relay
 ```
 
-Use `@domino-sdk/relay/authoring` for quest definitions, `/browser` for browser integrations, `/portal-proxy` for server proxies, and `/build` for bundling authored modules.
+| Import                           | For                                                                                        |
+| -------------------------------- | ------------------------------------------------------------------------------------------ |
+| `@domino-sdk/relay`              | The participant client (`createRelayClient`), `RelayError`, and the types it returns       |
+| `@domino-sdk/relay/browser`      | The browser client with durable submission recovery, wallet signers and sign-in options    |
+| `@domino-sdk/relay/react`        | React hooks over the browser client                                                        |
+| `@domino-sdk/relay/avatar`       | Generated default avatars (`avatarSrc`, `defaultAvatar`)                                   |
+| `@domino-sdk/relay/authoring`    | Quest, tracker, leaderboard, referral and engagement definitions, and evaluator types     |
+| `@domino-sdk/relay/schema`       | Zod schemas of Relay's API bodies, deployments, tracker records and observations           |
+| `@domino-sdk/relay/build`        | Bundling authored modules; needs `esbuild` installed                                       |
+| `@domino-sdk/relay/portal-proxy` | Server proxies and hosted app Workers                                                      |
+| `@domino-sdk/relay/vite`         | The Vite plugin that keeps server code out of the browser build                            |
+
+`@domino-sdk/relay/internal` is shared by Relay's own services and Console. It is not a supported API and can change in any release.
 
 Requires Node.js 24 for tooling. Proprietary software; `UNLICENSED`.

package/build.mjs

@@ -1,5 +1,21 @@
 import { resolve, dirname } from "node:path"
-import { build } from "esbuild"
+
+// esbuild is an optional peer dependency: only quest builds need it, so apps that use the runtime
+// client do not install its native binary. `@domino-sdk/relay-cli` depends on it.
+async function esbuild() {
+  try {
+    return await import("esbuild")
+  } catch (error) {
+    if (error?.code === "ERR_MODULE_NOT_FOUND") {
+      throw new Error(
+        "@domino-sdk/relay/build needs esbuild. Install it next to @domino-sdk/relay, or build with the domino CLI (@domino-sdk/relay-cli).",
+        { cause: error }
+      )
+    }
+
+    throw error
+  }
+}
 
 /** Bundle an authored quest without evaluating developer code in the build process. */
 export async function buildQuest(entry, options = {}) {
@@ -10,6 +26,7 @@ export async function buildQuest(entry, options = {}) {
     throw new Error("Invalid quest export name")
   }
 
+  const { build } = await esbuild()
   const result = await build({
     ...(options.exportName
       ? {

package/dist/authoring.d.ts

@@ -1,7 +1,309 @@
-import { A as AdmittedContent, O as Observation, T as TrackerTriggerContext, a as TrackerReader, X as XReader, I as ImageReader, D as DiscordMember, b as DiscordMessage, W as WalletConnection, S as SolanaBalance, L as LinkedWallet, c as WalletBalanceQuery, d as WalletBalance, e as TrackerDefinition, f as TrackerTriggerMode, g as TrackerWhere, o as observationTriggerSchema, h as TrackerTriggerPolicy, B as Budget, i as AuthoringIdentity, C as ContentMetric, j as IntegrationProvider, k as StreakPolicy, l as TextEvidence, U as UrlEvidence, m as TextOptions, n as UrlOptions } from './submission-input-CZDukyb3.js';
-export { E as EvmChainId, p as content, q as customSource, r as defineEngagementReward, s as defineLeaderboard, t as defineReferral, u as defineTracker, v as discord, w as formatUnits, x as isEvmChainId, y as parseUnits, z as perContent, F as pointLedgers, G as settings, H as streak, J as trackerTriggerContextSchema, K as x } from './submission-input-CZDukyb3.js';
 import { z } from 'zod';
-import { TextReviewInput, TextResult, PhotoResult, rewardSchema, triggerSchema, QuestPresentation, QuestProfile, QuizEvidence, Decision, TieredRewardDefinition } from './schema.js';
+import { C as ContentPolicy, g as ContentMetric, E as EngagementDefinition, l as leaderboardAuthoringSchema, r as referralAuthoringSchema, h as AdmittedContent, D as DiscordMember, T as TextEvidence, U as UrlEvidence, e as TextOptions, f as UrlOptions } from './submission-input-Bter6XiI.js';
+import { Q as QuizContent, a as StreakPolicy } from './streaks-CwGReWGt.js';
+import { T as TrackerDefinition, I as IdentityKind, t as trackerDefinitionSchema, R as ResourceSource, O as Observation, a as TrackerTriggerContext, b as TrackerReader, X as XReader, D as DiscordMessage, c as TrackerTriggerMode, d as TrackerWhere, o as observationTriggerSchema, e as TrackerTriggerPolicy, B as Budget, f as IntegrationProvider } from './integrations-C3Sp558f.js';
+export { g as trackerTriggerContextSchema } from './integrations-C3Sp558f.js';
+import { I as ImageReader } from './images-e6FW9QSx.js';
+import { d as TextReviewInput, e as TextResult, P as PhotoResult, r as rewardSchema, t as triggerSchema, Q as QuestPresentation, a as QuestProfile, b as QuizEvidence, D as Decision, f as TieredRewardDefinition } from './schema-DCapSPHz.js';
+import { c as WalletConnection, S as SolanaBalance, L as LinkedWallet, i as WalletBalanceQuery, j as WalletBalance } from './wallet-Bu6sqJvQ.js';
+export { E as EvmChainId, k as isEvmChainId } from './wallet-Bu6sqJvQ.js';
+export { f as formatUnits, p as parseUnits } from './units-CwgsPB_r.js';
+
+/** Legacy `id` names an authoring key, never a server resource ID. */
+type AuthoringIdentity = {
+    key: string;
+    id?: string;
+} | {
+    key?: never; /** @deprecated Use key. */
+    id: string;
+};
+
+/** Discover posts automatically; historical release remains an explicit policy. */
+declare function content(tracker: TrackerDefinition, policy?: Partial<Pick<ContentPolicy, "enrollment" | "posts" | "historical">>): {
+    kind: "automatic";
+    content: {
+        tracker: string;
+        window: {
+            start: number;
+            end?: number | undefined;
+        };
+        enrollment: "required" | "none";
+        posts: "after-enrollment" | "since-start";
+        historical: "staff" | "automatic" | "claim";
+    };
+};
+declare function perContent(): {
+    kind: "keyed";
+    perContent: true;
+    key: (ctx: {
+        content?: AdmittedContent | null;
+    }) => string;
+};
+/** One independent cumulative formula; management changes capture a new scoring boundary. */
+declare function defineEngagementReward<const M extends readonly [ContentMetric, ...ContentMetric[]]>(input: {
+    key: string;
+    qualifiedBy: string | {
+        key: string;
+    };
+    balance: string;
+    metrics: M;
+    baseline: "historical";
+    maxAgeMs?: number;
+    budget?: EngagementDefinition["budget"];
+    target: (input: {
+        metrics: Record<M[number], number>;
+    }) => number;
+}): {
+    key: string;
+    describe: () => {
+        key: string;
+        qualifiedBy: string;
+        balance: string;
+        metrics: ("likes" | "replies" | "reposts" | "quotes" | "views" | "bookmarks")[];
+        baseline: "historical";
+        maxAgeMs: number;
+        budget: {
+            projectDaily?: number | undefined;
+            memberDaily?: number | undefined;
+            projectLifetime?: number | undefined;
+        };
+    };
+    score(raw: unknown): {
+        target: number;
+        baseline: number;
+    };
+};
+/**
+ * One milestone per quest, after `days` consecutive community days with an accepted attempt.
+ * Multiple accepted attempts occupy one day. The day comes from the attempt's trusted occurrence
+ * time: a tracker record's (or observation's) `occurredAt` for `automatic({ tracker })`, and the
+ * submission's admission time for `manual()`, so a manual streak counts the days a member
+ * submitted. Not available on content quests or prerequisite-only `automatic()`.
+ */
+declare const streak: (options: Omit<StreakPolicy, "kind">) => StreakPolicy;
+declare function defineReferral(input: Omit<z.input<typeof referralAuthoringSchema>, "key" | "id"> & AuthoringIdentity): {
+    id: string;
+    title: string;
+    rewards: {
+        inviter: ({
+            kind: "tier";
+            reward: {
+                id: string;
+                title: string;
+                tiers: {
+                    id: string;
+                    title: string;
+                }[];
+                inventory: {
+                    kind: "untracked";
+                };
+                fulfillment: {
+                    kind: "staff-handover";
+                };
+            };
+            tier: string;
+        } | {
+            kind: "points";
+            balance: string;
+            amount: number;
+        })[];
+        invitee: ({
+            kind: "tier";
+            reward: {
+                id: string;
+                title: string;
+                tiers: {
+                    id: string;
+                    title: string;
+                }[];
+                inventory: {
+                    kind: "untracked";
+                };
+                fulfillment: {
+                    kind: "staff-handover";
+                };
+            };
+            tier: string;
+        } | {
+            kind: "points";
+            balance: string;
+            amount: number;
+        })[];
+    };
+    qualification: {
+        kind: "signup";
+    } | {
+        kind: "quest";
+        quest: string;
+    } | {
+        kind: "external";
+    };
+    enabled: boolean;
+    inviterGroup?: string | undefined;
+    milestones: {
+        id: string;
+        count: number;
+        rewards: ({
+            kind: "tier";
+            reward: {
+                id: string;
+                title: string;
+                tiers: {
+                    id: string;
+                    title: string;
+                }[];
+                inventory: {
+                    kind: "untracked";
+                };
+                fulfillment: {
+                    kind: "staff-handover";
+                };
+            };
+            tier: string;
+        } | {
+            kind: "points";
+            balance: string;
+            amount: number;
+        })[];
+    }[];
+    bonuses: {
+        id: string;
+        balance: string;
+        basisPoints: number;
+        external: boolean;
+        quests?: string[] | undefined;
+        durationDays?: number | undefined;
+        maxPoints?: number | undefined;
+    }[];
+    key: string;
+};
+declare function defineLeaderboard(input: Omit<z.input<typeof leaderboardAuthoringSchema>, "key" | "id"> & AuthoringIdentity): {
+    id: string;
+    title: string;
+    balance: string;
+    group?: string | undefined;
+    score: {
+        kind: "balance";
+    } | {
+        window: {
+            kind: "fixed";
+            start: number;
+            end: number;
+        } | {
+            kind: "all-time";
+        } | {
+            kind: "rolling";
+            days: number;
+        } | {
+            kind: "calendar";
+            period: "day" | "week" | "month";
+            timeZone: string;
+        };
+        kind: "earned";
+        quests?: string[] | undefined;
+    } | {
+        kind: "net";
+        window: {
+            kind: "fixed";
+            start: number;
+            end: number;
+        } | {
+            kind: "all-time";
+        } | {
+            kind: "rolling";
+            days: number;
+        } | {
+            kind: "calendar";
+            period: "day" | "week" | "month";
+            timeZone: string;
+        };
+    };
+    access: "participants" | "public";
+    key: string;
+};
+declare const x: {
+    search: (input: {
+        query: string;
+    }) => {
+        kind: "x-search";
+        query: string;
+    };
+};
+/**
+ * Records your own code sends with `trackers.ingest`. With `identities`, each record's author, and
+ * each named account in `accounts`, is a verified identity of one of those kinds, which Relay
+ * attributes to the member who verified it, so quests can trigger from the tracker. A record states
+ * each account's `kind` unless the source names exactly one.
+ */
+declare const customSource: (namespace: string, options?: {
+    identities?: IdentityKind[];
+    accounts?: string[];
+}) => {
+    kind: "custom";
+    namespace: string;
+    identities?: ("x" | "discord" | "member" | "wallet")[] | undefined;
+    accounts?: string[] | undefined;
+    authors?: "wallet" | undefined;
+};
+declare function defineTracker(input: z.input<typeof trackerDefinitionSchema>): TrackerDefinition;
+type ChannelTypes = Extract<ResourceSource, {
+    resource: "channel";
+}>["types"];
+declare const discord: {
+    roles(options?: {
+        assignable?: boolean;
+    }): ResourceSource;
+    channels(options?: {
+        types?: ChannelTypes;
+    }): ResourceSource;
+};
+declare const pointLedgers: () => ResourceSource;
+type Label = {
+    label: string;
+    description?: string;
+};
+declare const settings: {
+    pointLedger(options: Label & {
+        default: string;
+    }): z.ZodDefault<z.ZodString>;
+    datetime(options: Label & {
+        default: string;
+    }): z.ZodDefault<z.ZodPipe<z.ZodISODateTime, z.ZodTransform<string, string>>>;
+    resource(options: Label & {
+        source: ResourceSource;
+        default?: string;
+    }): z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>;
+    quiz(options: Label & {
+        default: QuizContent;
+    }): z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        prompt: z.ZodString;
+        choices: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strict>>;
+        correct: z.ZodString;
+    }, z.core.$strict>>>;
+    text(options: Label & {
+        default: string;
+        minLength?: number;
+        maxLength?: number;
+        multiline?: boolean;
+    }): z.ZodDefault<z.ZodString>;
+    integer(options: Label & {
+        default: number;
+        min: number;
+        max: number;
+    }): z.ZodDefault<z.ZodNumber>;
+    boolean(options: Label & {
+        default: boolean;
+    }): z.ZodDefault<z.ZodBoolean>;
+    choice<const T extends readonly [string, ...string[]]>(options: Label & {
+        options: T;
+        default: T[number];
+    }): z.ZodDefault<z.ZodEnum<{ [k_1 in T[number]]: k_1; } extends infer T_1 ? { [k in keyof T_1]: T_1[k]; } : never>>;
+    object<T extends Record<string, z.ZodType>>(shape: T): z.ZodObject<{ -readonly [P in keyof T]: T[P]; }, z.core.$strict>;
+};
 
 type Reward = z.infer<typeof rewardSchema>;
 declare const points: (balance: string, amount: number) => {
@@ -99,7 +401,7 @@ declare function automatic(input: TrackerTriggerInput): {
 declare const budget: (definition: Budget) => {
     id: string;
     scope: "member" | "project";
-    period: "lifetime" | "day" | "week";
+    period: "day" | "lifetime" | "week";
     limit: number;
     cost: number | {
         balance: string;
@@ -326,6 +628,12 @@ declare function defineQuest<T extends Record<string, z.ZodType>, const G extend
      */
     profile?: QuestProfile;
     budgets?: Budget[];
+    /**
+     * Whether staff can review this quest's attempts. Human review is on unless this returns
+     * `{ enabled: false }`. With it off, `decision.review(...)` becomes a reject that keeps the
+     * review reason, and the attempt records `requestedReview: true`; Console shows "Would have
+     * gone to review; human review is off".
+     */
     review?: (ctx: {
         settings: z.output<z.ZodObject<T>>;
     }) => {
@@ -393,12 +701,12 @@ declare function defineQuest<T extends Record<string, z.ZodType>, const G extend
             kind: "resource";
             default: string;
             source: {
-                provider: "domino";
-                resource: "point-ledger";
-            } | {
                 provider: "discord";
                 resource: "channel";
                 types: ("text" | "announcement")[];
+            } | {
+                provider: "domino";
+                resource: "point-ledger";
             } | {
                 provider: "discord";
                 resource: "role";
@@ -531,7 +839,7 @@ declare function defineQuest<T extends Record<string, z.ZodType>, const G extend
                 minLength: number;
                 maxLength: number;
             };
-            actor?: "staff" | "member" | undefined;
+            actor?: "member" | "staff" | undefined;
         } | {
             kind: "manual";
             input: "url";
@@ -539,11 +847,11 @@ declare function defineQuest<T extends Record<string, z.ZodType>, const G extend
                 required: boolean;
                 allowedHosts?: string[] | undefined;
             };
-            actor?: "staff" | "member" | undefined;
+            actor?: "member" | "staff" | undefined;
         } | {
             kind: "manual";
-            input: "photo" | "quiz" | "none";
-            actor?: "staff" | "member" | undefined;
+            input: "quiz" | "photo" | "none";
+            actor?: "member" | "staff" | undefined;
         };
         requires: {
             quest: string;
@@ -557,11 +865,11 @@ declare function defineQuest<T extends Record<string, z.ZodType>, const G extend
         } | {
             kind: "keyed";
         };
-        visibility: "visible" | "hidden";
+        visibility: "hidden" | "visible";
         budgets: {
             id: string;
             scope: "member" | "project";
-            period: "lifetime" | "day" | "week";
+            period: "day" | "lifetime" | "week";
             limit: number;
             cost: number | {
                 balance: string;
@@ -585,4 +893,4 @@ declare function defineQuest<T extends Record<string, z.ZodType>, const G extend
  * Console instances receive independent quest identities and pinned versions. */
 declare const defineQuestType: typeof defineQuest;
 
-export { type EvaluationContext, type PerformanceOutcome, TrackerTriggerContext, type TrackerTriggerInput, WalletBalance, WalletBalanceQuery, automatic, budget, completed, decision, defineQuest, defineQuestType, defineTieredReward, discordRole, evaluators, evidence, keyed, manual, once, points, staffHandover, untracked };
+export { type EvaluationContext, ImageReader, type PerformanceOutcome, TrackerReader, TrackerTriggerContext, type TrackerTriggerInput, WalletBalance, WalletBalanceQuery, XReader, automatic, budget, completed, content, customSource, decision, defineEngagementReward, defineLeaderboard, defineQuest, defineQuestType, defineReferral, defineTieredReward, defineTracker, discord, discordRole, evaluators, evidence, keyed, manual, once, perContent, pointLedgers, points, settings, staffHandover, streak, untracked, x };