@domino-sdk/relay 1.61.0 → 1.63.0

package/dist/capability-error-CuI_F7yM.d.ts

@@ -0,0 +1,296 @@
+import * as z from 'zod';
+
+declare const completionPolicySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"streak">;
+    days: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"progress">;
+    goal: z.ZodObject<{
+        kind: z.ZodLiteral<"count">;
+        count: z.ZodNumber;
+    }, z.core.$strict>;
+    window: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"lifetime">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"calendar">;
+        period: z.ZodEnum<{
+            day: "day";
+            week: "week";
+            month: "month";
+        }>;
+        latenessMs: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"rolling">;
+        durationMs: z.ZodNumber;
+    }, z.core.$strict>], "kind">;
+    repeat: z.ZodDefault<z.ZodEnum<{
+        repeat: "repeat";
+        once: "once";
+    }>>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"once">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"keyed">;
+    across: z.ZodOptional<z.ZodLiteral<"members">>;
+}, z.core.$strict>], "kind">;
+declare const completionKeySchema: z.ZodString;
+declare const budgetSchema: z.ZodObject<{
+    id: z.ZodString;
+    scope: z.ZodEnum<{
+        member: "member";
+        project: "project";
+    }>;
+    period: z.ZodEnum<{
+        lifetime: "lifetime";
+        day: "day";
+        week: "week";
+        month: "month";
+    }>;
+    limit: z.ZodNumber;
+    cost: z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
+        balance: z.ZodString;
+    }, z.core.$strict>]>;
+}, z.core.$strict>;
+type Budget = z.infer<typeof budgetSchema>;
+/**
+ * A budget counted per tracker record author: the account that caused the record, such as a
+ * reaction's reactor, whether or not it belongs to a member. It caps what one person gives when a
+ * quest pays someone else. Only quests with a tracker trigger take one, in their `authorBudgets`.
+ */
+declare const authorBudgetSchema: z.ZodObject<{
+    id: z.ZodString;
+    period: z.ZodEnum<{
+        lifetime: "lifetime";
+        day: "day";
+        week: "week";
+        month: "month";
+    }>;
+    limit: z.ZodNumber;
+    cost: z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
+        balance: z.ZodString;
+    }, z.core.$strict>]>;
+    scope: z.ZodLiteral<"author">;
+}, z.core.$strict>;
+type AuthorBudget = z.infer<typeof authorBudgetSchema>;
+/**
+ * One of the member's accepted, unrevoked quest completions, as `ctx.member.completions()` reads
+ * it. `quest` is the quest's key and `key` the completion key. `completedAt` is when it was
+ * recorded, in epoch milliseconds on the member's clock (a test member's advanced one); null for
+ * older completions recorded without a time.
+ */
+declare const memberCompletionSchema: z.ZodObject<{
+    quest: z.ZodString;
+    key: z.ZodString;
+    completedAt: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+type MemberCompletion = z.infer<typeof memberCompletionSchema>;
+/**
+ * The most completions one `ctx.member.completions()` call returns, and its default `limit`.
+ *
+ * @deprecated Use `limits.memberCompletions`, which a 1.x release can raise.
+ */
+declare const maxMemberCompletions = 100;
+
+declare const resourceSourceSchema: z.ZodUnion<readonly [z.ZodObject<{
+    provider: z.ZodLiteral<"domino">;
+    resource: z.ZodLiteral<"point-ledger">;
+}, z.core.$strict>, z.ZodUnion<readonly [z.ZodObject<{
+    provider: z.ZodLiteral<"discord">;
+    resource: z.ZodLiteral<"channel">;
+    types: z.ZodArray<z.ZodEnum<{
+        text: "text";
+        announcement: "announcement";
+    }>>;
+    postable: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strict>, z.ZodObject<{
+    provider: z.ZodLiteral<"discord">;
+    resource: z.ZodLiteral<"role">;
+    assignable: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>]>]>;
+type ResourceSource = z.infer<typeof resourceSourceSchema>;
+declare const resourceRequestSchema: z.ZodObject<{
+    source: z.ZodUnion<readonly [z.ZodObject<{
+        provider: z.ZodLiteral<"domino">;
+        resource: z.ZodLiteral<"point-ledger">;
+    }, z.core.$strict>, z.ZodUnion<readonly [z.ZodObject<{
+        provider: z.ZodLiteral<"discord">;
+        resource: z.ZodLiteral<"channel">;
+        types: z.ZodArray<z.ZodEnum<{
+            text: "text";
+            announcement: "announcement";
+        }>>;
+        postable: z.ZodOptional<z.ZodLiteral<true>>;
+    }, z.core.$strict>, z.ZodObject<{
+        provider: z.ZodLiteral<"discord">;
+        resource: z.ZodLiteral<"role">;
+        assignable: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>]>]>;
+    query: z.ZodOptional<z.ZodString>;
+    cursor: z.ZodOptional<z.ZodString>;
+    ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+declare const resourceOptionsSchema: z.ZodObject<{
+    revision: z.ZodNumber;
+    options: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        group: z.ZodOptional<z.ZodString>;
+        disabledReason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    nextCursor: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    cursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+type ResourceOption = z.infer<typeof resourceOptionsSchema>["options"][number];
+
+/**
+ * A YouTube Short's body, as `content()` quests read it in `ctx.tracker.content.body`. Every field
+ * is what YouTube reported when Relay last read the video.
+ *
+ * @compat output
+ */
+declare const youtubeShortBodySchema: z.ZodObject<{
+    title: z.ZodString;
+    description: z.ZodString;
+    tags: z.ZodArray<z.ZodString>;
+    durationSeconds: z.ZodNumber;
+    publishedAt: z.ZodNumber;
+}, z.core.$strip>;
+type YouTubeShortBody = z.infer<typeof youtubeShortBodySchema>;
+/** The counters a YouTube Short's samples measure. A counter YouTube hides is unknown, never zero. */
+declare const youtubeShortMetrics: readonly ["views", "likes", "comments"];
+type YouTubeShortMetric = (typeof youtubeShortMetrics)[number];
+
+/**
+ * A TikTok video's body, as `content()` quests read it in `ctx.tracker.content.body`. Every field
+ * is what TikTok reported when Relay last read the video.
+ *
+ * @compat output
+ */
+declare const tiktokVideoBodySchema: z.ZodObject<{
+    title: z.ZodString;
+    description: z.ZodString;
+    durationSeconds: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    createdAt: z.ZodNumber;
+    shareUrl: z.ZodString;
+    isAigc: z.ZodBoolean;
+}, z.core.$strip>;
+type TikTokVideoBody = z.infer<typeof tiktokVideoBodySchema>;
+/** The counters a TikTok video's samples measure. A counter TikTok omits is unknown, never zero. */
+declare const tiktokVideoMetrics: readonly ["views", "likes", "comments", "shares"];
+type TikTokVideoMetric = (typeof tiktokVideoMetrics)[number];
+
+/**
+ * An announcement's text, at most 1000 characters, with `{placeholder}`s (`announcementPlaceholders`)
+ * that Relay fills when it posts. `{{` and `}}` are literal braces.
+ */
+declare const announcementTextSchema: z.ZodString;
+/** An announcement Domino's bot posts in one of the project's connected Telegram chats. */
+declare const telegramAnnouncementSchema: z.ZodObject<{
+    action: z.ZodLiteral<"post-message">;
+    text: z.ZodString;
+    replyToTriggeringMessage: z.ZodOptional<z.ZodBoolean>;
+    provider: z.ZodLiteral<"telegram">;
+    chat: z.ZodString;
+}, z.core.$strict>;
+/** An announcement Domino's bot posts in a channel of the project's connected Discord server. */
+declare const discordAnnouncementSchema: z.ZodObject<{
+    action: z.ZodLiteral<"post-message">;
+    text: z.ZodString;
+    replyToTriggeringMessage: z.ZodOptional<z.ZodBoolean>;
+    provider: z.ZodLiteral<"discord">;
+    channel: z.ZodString;
+}, z.core.$strict>;
+/**
+ * A message Relay posts when a completion of the quest pays, after its rewards commit. A failed
+ * post never undoes the rewards. Build one with `telegram.postMessage()` or
+ * `discord.postMessage()`.
+ */
+declare const announcementSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    action: z.ZodLiteral<"post-message">;
+    text: z.ZodString;
+    replyToTriggeringMessage: z.ZodOptional<z.ZodBoolean>;
+    provider: z.ZodLiteral<"telegram">;
+    chat: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    action: z.ZodLiteral<"post-message">;
+    text: z.ZodString;
+    replyToTriggeringMessage: z.ZodOptional<z.ZodBoolean>;
+    provider: z.ZodLiteral<"discord">;
+    channel: z.ZodString;
+}, z.core.$strict>], "provider">;
+type Announcement = z.infer<typeof announcementSchema>;
+
+/**
+ * Why an evaluator capability could not answer:
+ *
+ * - `not-linked`: the call needs a member account that is not linked, and its result cannot be
+ *   null, such as an image check of the member's X profile picture. Readers of the member's own
+ *   accounts return `null` instead.
+ * - `provider-unavailable`: the provider (X, Discord, a chain RPC, AI review) did not answer, or
+ *   the project's integration cannot reach it.
+ * - `author-error`: the call cannot be answered as written: invalid input, an undeclared
+ *   integration, an unknown tracker, a chain Relay does not read, a wallet the member never
+ *   linked, or an image that does not exist.
+ *
+ * Later versions can add codes. Relay also sends codes this tuple does not list, as SDK 1.x keeps
+ * it fixed:
+ *
+ * - `integration-required`: the project's integration needs configuration before the call can
+ *   answer.
+ * - `capability-limit`: the evaluation run already made its eight capability calls, which all
+ *   capabilities share. Never retryable: the run makes the same calls again.
+ *
+ * Treat an unknown code as a failure its `message` explains.
+ */
+declare const capabilityErrorCodes: readonly ["not-linked", "provider-unavailable", "author-error"];
+/** @compat open */
+type KnownCapabilityErrorCode = (typeof capabilityErrorCodes)[number];
+/** A known code, or one a newer Relay added. */
+type CapabilityErrorCode = KnownCapabilityErrorCode | (string & {});
+/**
+ * A capability failure as it crosses the sandbox boundary and as Relay captures it. Open, so a
+ * newer Relay can add codes and fields without breaking an older evaluator or Worker.
+ */
+declare const capabilityFailureSchema: z.ZodObject<{
+    code: z.ZodString;
+    message: z.ZodString;
+    retryable: z.ZodBoolean;
+}, z.core.$loose>;
+type CapabilityFailure = z.infer<typeof capabilityFailureSchema>;
+/**
+ * Thrown by an evaluator capability (`ctx.x`, `ctx.discord`, `ctx.wallet`, `ctx.trackers`,
+ * `ctx.images`, `ctx.review`) that could not answer. A capability whose subject is missing (an
+ * account the member has not linked, a deleted post or message) returns `null` instead of
+ * throwing.
+ *
+ * Catch it to decide yourself; rethrow anything else. An uncaught retryable error makes Relay
+ * retry the attempt later; an uncaught one that is not retryable fails it.
+ *
+ * ```ts
+ * try {
+ *   return (await ctx.x.follows({ userId })) ? decision.accept() : decision.reject({ reason })
+ * } catch (error) {
+ *   if (error instanceof CapabilityError && error.code === "provider-unavailable")
+ *     return decision.review({ reason: "X is unavailable" })
+ *   throw error
+ * }
+ * ```
+ */
+declare class CapabilityError extends Error {
+    readonly code: CapabilityErrorCode;
+    readonly retryable: boolean;
+    constructor(code: CapabilityErrorCode, message: string, options?: {
+        retryable?: boolean;
+    });
+    static [Symbol.hasInstance](value: unknown): boolean;
+    /**
+     * The error for a captured or transported failure. A code this SDK does not know is never
+     * retryable: nothing tells it a retry would help.
+     */
+    static from(failure: CapabilityFailure): CapabilityError;
+}
+
+export { type AuthorBudget as A, type Budget as B, CapabilityError as C, type KnownCapabilityErrorCode as K, type MemberCompletion as M, type ResourceSource as R, type TikTokVideoBody as T, type YouTubeShortBody as Y, type Announcement as a, type CapabilityErrorCode as b, type TikTokVideoMetric as c, type YouTubeShortMetric as d, capabilityErrorCodes as e, type CapabilityFailure as f, type ResourceOption as g, announcementSchema as h, announcementTextSchema as i, authorBudgetSchema as j, budgetSchema as k, capabilityFailureSchema as l, completionKeySchema as m, completionPolicySchema as n, discordAnnouncementSchema as o, maxMemberCompletions as p, memberCompletionSchema as q, resourceOptionsSchema as r, resourceRequestSchema as s, resourceSourceSchema as t, telegramAnnouncementSchema as u, tiktokVideoBodySchema as v, tiktokVideoMetrics as w, youtubeShortMetrics as x, youtubeShortBodySchema as y };