@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.0

package/dist/contracts/problems.d.ts

@@ -0,0 +1,106 @@
+import { z } from "zod";
+/** Stable problem codes (docs/05 §5). Hosts with a closed list map them through `ports.errors`. */
+export declare const TELEGRAM_PROBLEM_CODES: readonly ["feature_disabled", "bot_token_invalid", "bot_token_mismatch", "bot_unreachable", "webhook_url_missing", "webhook_failed", "chat_not_found", "chat_blocked", "link_expired", "link_used", "destination_not_allowed", "template_invalid", "template_variable_unknown", "provider_unknown", "provider_forbidden", "schedule_rule_invalid", "timezone_invalid", "recipient_empty", "send_text_rejected", "file_too_large", "renderer_unavailable", "delivery_not_retryable", "schema_outdated", "unauthenticated", "forbidden", "not_found", "validation_failed", "rate_limited", "internal_error"];
+/** Zod enum of {@link TELEGRAM_PROBLEM_CODES}. */
+export declare const TelegramProblemCode: z.ZodEnum<{
+  timezone_invalid: "timezone_invalid";
+  recipient_empty: "recipient_empty";
+  schedule_rule_invalid: "schedule_rule_invalid";
+  feature_disabled: "feature_disabled";
+  bot_token_invalid: "bot_token_invalid";
+  bot_token_mismatch: "bot_token_mismatch";
+  bot_unreachable: "bot_unreachable";
+  webhook_url_missing: "webhook_url_missing";
+  webhook_failed: "webhook_failed";
+  chat_not_found: "chat_not_found";
+  chat_blocked: "chat_blocked";
+  link_expired: "link_expired";
+  link_used: "link_used";
+  destination_not_allowed: "destination_not_allowed";
+  template_invalid: "template_invalid";
+  template_variable_unknown: "template_variable_unknown";
+  provider_unknown: "provider_unknown";
+  provider_forbidden: "provider_forbidden";
+  send_text_rejected: "send_text_rejected";
+  file_too_large: "file_too_large";
+  renderer_unavailable: "renderer_unavailable";
+  delivery_not_retryable: "delivery_not_retryable";
+  schema_outdated: "schema_outdated";
+  unauthenticated: "unauthenticated";
+  forbidden: "forbidden";
+  not_found: "not_found";
+  validation_failed: "validation_failed";
+  rate_limited: "rate_limited";
+  internal_error: "internal_error";
+}>;
+export type TelegramProblemCode = z.infer<typeof TelegramProblemCode>;
+/** Default HTTP status per code. */
+export declare const PROBLEM_STATUS: Readonly<Record<TelegramProblemCode, number>>;
+/** One template syntax error (1-based line and column). */
+export declare const TemplateError: z.ZodObject<{
+  line: z.ZodNumber;
+  column: z.ZodNumber;
+  message: z.ZodString;
+  locale: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TemplateError = z.infer<typeof TemplateError>;
+/** One field-level validation issue. */
+export declare const FieldIssue: z.ZodObject<{
+  path: z.ZodString;
+  message: z.ZodString;
+}, z.core.$strip>;
+export type FieldIssue = z.infer<typeof FieldIssue>;
+/** RFC 9457 problem+json body with the plugin's stable `code`. */
+export declare const TelegramProblem: z.ZodObject<{
+  type: z.ZodDefault<z.ZodString>;
+  title: z.ZodString;
+  status: z.ZodNumber;
+  detail: z.ZodOptional<z.ZodString>;
+  instance: z.ZodOptional<z.ZodString>;
+  code: z.ZodEnum<{
+    timezone_invalid: "timezone_invalid";
+    recipient_empty: "recipient_empty";
+    schedule_rule_invalid: "schedule_rule_invalid";
+    feature_disabled: "feature_disabled";
+    bot_token_invalid: "bot_token_invalid";
+    bot_token_mismatch: "bot_token_mismatch";
+    bot_unreachable: "bot_unreachable";
+    webhook_url_missing: "webhook_url_missing";
+    webhook_failed: "webhook_failed";
+    chat_not_found: "chat_not_found";
+    chat_blocked: "chat_blocked";
+    link_expired: "link_expired";
+    link_used: "link_used";
+    destination_not_allowed: "destination_not_allowed";
+    template_invalid: "template_invalid";
+    template_variable_unknown: "template_variable_unknown";
+    provider_unknown: "provider_unknown";
+    provider_forbidden: "provider_forbidden";
+    send_text_rejected: "send_text_rejected";
+    file_too_large: "file_too_large";
+    renderer_unavailable: "renderer_unavailable";
+    delivery_not_retryable: "delivery_not_retryable";
+    schema_outdated: "schema_outdated";
+    unauthenticated: "unauthenticated";
+    forbidden: "forbidden";
+    not_found: "not_found";
+    validation_failed: "validation_failed";
+    rate_limited: "rate_limited";
+    internal_error: "internal_error";
+  }>;
+  errors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    line: z.ZodNumber;
+    column: z.ZodNumber;
+    message: z.ZodString;
+    locale: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>>;
+  issues: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    path: z.ZodString;
+    message: z.ZodString;
+  }, z.core.$strip>>>;
+  retryAfter: z.ZodOptional<z.ZodNumber>;
+  reasons: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type TelegramProblem = z.infer<typeof TelegramProblem>;
+/** `Content-Type` of every plugin error response. */
+export declare const PROBLEM_CONTENT_TYPE = "application/problem+json";

package/dist/contracts/problems.js

@@ -0,0 +1,101 @@
+import { z } from "zod";
+// src/contracts/problems.ts
+/** Stable problem codes (docs/05 §5). Hosts with a closed list map them through `ports.errors`. */
+const TELEGRAM_PROBLEM_CODES = [
+	"feature_disabled",
+	"bot_token_invalid",
+	"bot_token_mismatch",
+	"bot_unreachable",
+	"webhook_url_missing",
+	"webhook_failed",
+	"chat_not_found",
+	"chat_blocked",
+	"link_expired",
+	"link_used",
+	"destination_not_allowed",
+	"template_invalid",
+	"template_variable_unknown",
+	"provider_unknown",
+	"provider_forbidden",
+	"schedule_rule_invalid",
+	"timezone_invalid",
+	"recipient_empty",
+	"send_text_rejected",
+	"file_too_large",
+	"renderer_unavailable",
+	"delivery_not_retryable",
+	"schema_outdated",
+	"unauthenticated",
+	"forbidden",
+	"not_found",
+	"validation_failed",
+	"rate_limited",
+	"internal_error"
+];
+/** Zod enum of {@link TELEGRAM_PROBLEM_CODES}. */
+const TelegramProblemCode = z.enum(TELEGRAM_PROBLEM_CODES);
+/** Default HTTP status per code. */
+const PROBLEM_STATUS = {
+	feature_disabled: 404,
+	bot_token_invalid: 422,
+	bot_token_mismatch: 422,
+	bot_unreachable: 502,
+	webhook_url_missing: 422,
+	webhook_failed: 502,
+	chat_not_found: 404,
+	chat_blocked: 409,
+	link_expired: 410,
+	link_used: 409,
+	destination_not_allowed: 403,
+	template_invalid: 422,
+	template_variable_unknown: 422,
+	provider_unknown: 422,
+	provider_forbidden: 403,
+	schedule_rule_invalid: 422,
+	timezone_invalid: 422,
+	recipient_empty: 422,
+	send_text_rejected: 422,
+	file_too_large: 413,
+	renderer_unavailable: 501,
+	delivery_not_retryable: 409,
+	schema_outdated: 503,
+	unauthenticated: 401,
+	forbidden: 403,
+	not_found: 404,
+	validation_failed: 400,
+	rate_limited: 429,
+	internal_error: 500
+};
+/** One template syntax error (1-based line and column). */
+const TemplateError = z.object({
+	line: z.number().int().min(1),
+	column: z.number().int().min(1),
+	message: z.string(),
+	/** Body locale the error is in, for multi-locale templates. */
+	locale: z.string().optional()
+});
+/** One field-level validation issue. */
+const FieldIssue = z.object({
+	path: z.string(),
+	message: z.string()
+});
+/** RFC 9457 problem+json body with the plugin's stable `code`. */
+const TelegramProblem = z.object({
+	type: z.string().default("about:blank"),
+	title: z.string(),
+	status: z.number().int().min(400).max(599),
+	detail: z.string().optional(),
+	instance: z.string().optional(),
+	code: TelegramProblemCode,
+	/** `template_invalid`: syntax errors. */
+	errors: z.array(TemplateError).optional(),
+	/** `validation_failed`: field issues. */
+	issues: z.array(FieldIssue).optional(),
+	/** `rate_limited`: seconds to wait. */
+	retryAfter: z.number().int().nonnegative().optional(),
+	/** `send_text_rejected`: the failed content checks. */
+	reasons: z.array(z.string()).optional()
+});
+/** `Content-Type` of every plugin error response. */
+const PROBLEM_CONTENT_TYPE = "application/problem+json";
+export { FieldIssue, PROBLEM_CONTENT_TYPE, PROBLEM_STATUS, TELEGRAM_PROBLEM_CODES, TelegramProblem, TelegramProblemCode, TemplateError };

package/dist/contracts/recipients.d.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+/**
+ * Who receives a message. Built-in kinds plus host audiences from `defineAudience`
+ * (`{ audience: "projectTeam", ref: "P-12" }`).
+ */
+export declare const RecipientSpec: z.ZodUnion<readonly [z.ZodObject<{
+  destination: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+  chat: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+  user: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+  role: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+  allLinked: z.ZodLiteral<true>;
+}, z.core.$strict>, z.ZodObject<{
+  audience: z.ZodString;
+  ref: z.ZodString;
+}, z.core.$strict>]>;
+export type RecipientSpec = z.infer<typeof RecipientSpec>;
+/** 1–100 recipient specs; an empty list fails with `recipient_empty`. */
+export declare const Recipients: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+  destination: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+  chat: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+  user: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+  role: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+  allLinked: z.ZodLiteral<true>;
+}, z.core.$strict>, z.ZodObject<{
+  audience: z.ZodString;
+  ref: z.ZodString;
+}, z.core.$strict>]>>;
+export type Recipients = z.infer<typeof Recipients>;

package/dist/contracts/recipients.js

@@ -0,0 +1,22 @@
+import { Id } from "./common.js";
+import { Slug } from "./destinations.js";
+import { z } from "zod";
+// src/contracts/recipients.ts
+/**
+* Who receives a message. Built-in kinds plus host audiences from `defineAudience`
+* (`{ audience: "projectTeam", ref: "P-12" }`).
+*/
+const RecipientSpec = z.union([
+	z.strictObject({ destination: Slug }),
+	z.strictObject({ chat: Id }),
+	z.strictObject({ user: z.string().min(1) }),
+	z.strictObject({ role: z.string().min(1) }),
+	z.strictObject({ allLinked: z.literal(true) }),
+	z.strictObject({
+		audience: z.string().regex(/^[a-zA-Z][a-zA-Z0-9_]{0,31}$/),
+		ref: z.string().min(1).max(128)
+	})
+]);
+/** 1–100 recipient specs; an empty list fails with `recipient_empty`. */
+const Recipients = z.array(RecipientSpec).min(1, "recipient_empty").max(100);
+export { RecipientSpec, Recipients };

package/dist/contracts/schedules.d.ts

@@ -0,0 +1,276 @@
+import { z } from "zod";
+/** Weekday keys used by weekly rules. */
+export declare const WEEKDAYS: readonly ["mon", "tue", "wed", "thu", "fri", "sat", "sun"];
+/** Zod enum of {@link WEEKDAYS}. */
+export declare const Weekday: z.ZodEnum<{
+  mon: "mon";
+  tue: "tue";
+  wed: "wed";
+  thu: "thu";
+  fri: "fri";
+  sat: "sat";
+  sun: "sun";
+}>;
+export type Weekday = z.infer<typeof Weekday>;
+/** 5-field cron (minute hour day-of-month month day-of-week). Seconds and year fields are rejected. */
+export declare const CronExpr: z.ZodString;
+/** Local wall-clock date-time `YYYY-MM-DDTHH:MM`, read in the schedule's time zone. */
+export declare const LocalDateTime: z.ZodString;
+/** When a schedule fires. All times are local to the schedule's `timezone`. */
+export declare const ScheduleRule: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  kind: z.ZodLiteral<"daily">;
+  at: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  kind: z.ZodLiteral<"weekly">;
+  days: z.ZodArray<z.ZodEnum<{
+    mon: "mon";
+    tue: "tue";
+    wed: "wed";
+    thu: "thu";
+    fri: "fri";
+    sat: "sat";
+    sun: "sun";
+  }>>;
+  at: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  kind: z.ZodLiteral<"monthly">;
+  day: z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"last">]>;
+  at: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  kind: z.ZodLiteral<"cron">;
+  expr: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  kind: z.ZodLiteral<"once">;
+  at: z.ZodString;
+}, z.core.$strip>], "kind">;
+export type ScheduleRule = z.infer<typeof ScheduleRule>;
+/** The `kind` values of {@link ScheduleRule}. */
+export declare const SCHEDULE_RULE_KINDS: readonly ["daily", "weekly", "monthly", "cron", "once"];
+/** Zod enum of {@link SCHEDULE_RULE_KINDS}. */
+export declare const ScheduleRuleKind: z.ZodEnum<{
+  daily: "daily";
+  weekly: "weekly";
+  monthly: "monthly";
+  cron: "cron";
+  once: "once";
+}>;
+export type ScheduleRuleKind = z.infer<typeof ScheduleRuleKind>;
+/** What to do with a slot found more than `missedGraceMin` late: `skip` it, or `run_once` (latest slot only). */
+export declare const MISSED_POLICIES: readonly ["skip", "run_once"];
+/** Zod enum of {@link MISSED_POLICIES}. */
+export declare const MissedPolicy: z.ZodEnum<{
+  run_once: "run_once";
+  skip: "skip";
+}>;
+export type MissedPolicy = z.infer<typeof MissedPolicy>;
+/** Run outcome; `partial` = some deliveries queued before an error, `skipped` = missed-run policy skipped it. */
+export declare const SCHEDULE_RUN_STATUSES: readonly ["running", "done", "partial", "failed", "skipped"];
+/** Zod enum of {@link SCHEDULE_RUN_STATUSES}. */
+export declare const ScheduleRunStatus: z.ZodEnum<{
+  running: "running";
+  failed: "failed";
+  done: "done";
+  partial: "partial";
+  skipped: "skipped";
+}>;
+export type ScheduleRunStatus = z.infer<typeof ScheduleRunStatus>;
+/** What started a run: the rule (`schedule`), or `run-now` (`manual`). */
+export declare const SCHEDULE_RUN_TRIGGERS: readonly ["schedule", "manual"];
+/** Zod enum of {@link SCHEDULE_RUN_TRIGGERS}. */
+export declare const ScheduleRunTrigger: z.ZodEnum<{
+  schedule: "schedule";
+  manual: "manual";
+}>;
+export type ScheduleRunTrigger = z.infer<typeof ScheduleRunTrigger>;
+/** A recurring templated send (`/admin/schedules`, permission `telegram.schedules.manage`). */
+export declare const ScheduleDto: z.ZodObject<{
+  id: z.ZodString;
+  name: z.ZodString;
+  rule: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"daily">;
+    at: z.ZodString;
+  }, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"weekly">;
+    days: z.ZodArray<z.ZodEnum<{
+      mon: "mon";
+      tue: "tue";
+      wed: "wed";
+      thu: "thu";
+      fri: "fri";
+      sat: "sat";
+      sun: "sun";
+    }>>;
+    at: z.ZodString;
+  }, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"monthly">;
+    day: z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"last">]>;
+    at: z.ZodString;
+  }, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"cron">;
+    expr: z.ZodString;
+  }, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"once">;
+    at: z.ZodString;
+  }, z.core.$strip>], "kind">;
+  timezone: z.ZodString;
+  templateId: z.ZodString;
+  params: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  recipients: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+    destination: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    chat: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    user: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    role: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    allLinked: z.ZodLiteral<true>;
+  }, z.core.$strict>, z.ZodObject<{
+    audience: z.ZodString;
+    ref: z.ZodString;
+  }, z.core.$strict>]>>;
+  personalize: z.ZodBoolean;
+  missedPolicy: z.ZodEnum<{
+    run_once: "run_once";
+    skip: "skip";
+  }>;
+  missedGraceMin: z.ZodNumber;
+  enabled: z.ZodBoolean;
+  pausedUntil: z.ZodNullable<z.ZodNumber>;
+  nextRunAt: z.ZodNullable<z.ZodNumber>;
+  lastRunAt: z.ZodNullable<z.ZodNumber>;
+  lastStatus: z.ZodNullable<z.ZodEnum<{
+    running: "running";
+    failed: "failed";
+    done: "done";
+    partial: "partial";
+    skipped: "skipped";
+  }>>;
+  createdBy: z.ZodNullable<z.ZodString>;
+  createdAt: z.ZodNumber;
+  updatedAt: z.ZodNumber;
+}, z.core.$strip>;
+export type ScheduleDto = z.infer<typeof ScheduleDto>;
+/** `POST`/`PUT /admin/schedules` body (defaults: personalize, `run_once`, 30 min grace, enabled). */
+export declare const ScheduleSave: z.ZodObject<{
+  name: z.ZodString;
+  rule: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"daily">;
+    at: z.ZodString;
+  }, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"weekly">;
+    days: z.ZodArray<z.ZodEnum<{
+      mon: "mon";
+      tue: "tue";
+      wed: "wed";
+      thu: "thu";
+      fri: "fri";
+      sat: "sat";
+      sun: "sun";
+    }>>;
+    at: z.ZodString;
+  }, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"monthly">;
+    day: z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"last">]>;
+    at: z.ZodString;
+  }, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"cron">;
+    expr: z.ZodString;
+  }, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"once">;
+    at: z.ZodString;
+  }, z.core.$strip>], "kind">;
+  timezone: z.ZodOptional<z.ZodString>;
+  templateId: z.ZodString;
+  params: z.ZodDefault<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+  recipients: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+    destination: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    chat: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    user: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    role: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    allLinked: z.ZodLiteral<true>;
+  }, z.core.$strict>, z.ZodObject<{
+    audience: z.ZodString;
+    ref: z.ZodString;
+  }, z.core.$strict>]>>;
+  personalize: z.ZodDefault<z.ZodBoolean>;
+  missedPolicy: z.ZodDefault<z.ZodEnum<{
+    run_once: "run_once";
+    skip: "skip";
+  }>>;
+  missedGraceMin: z.ZodDefault<z.ZodNumber>;
+  enabled: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type ScheduleSave = z.infer<typeof ScheduleSave>;
+/** One schedule run (`GET /admin/schedules/:id/runs`). */
+export declare const ScheduleRunDto: z.ZodObject<{
+  id: z.ZodString;
+  scheduleId: z.ZodString;
+  slotAt: z.ZodNumber;
+  trigger: z.ZodEnum<{
+    schedule: "schedule";
+    manual: "manual";
+  }>;
+  startedAt: z.ZodNumber;
+  finishedAt: z.ZodNullable<z.ZodNumber>;
+  status: z.ZodEnum<{
+    running: "running";
+    failed: "failed";
+    done: "done";
+    partial: "partial";
+    skipped: "skipped";
+  }>;
+  deliveries: z.ZodNumber;
+  error: z.ZodNullable<z.ZodString>;
+  templateVersion: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type ScheduleRunDto = z.infer<typeof ScheduleRunDto>;
+/** `POST /admin/schedules/next-runs`. */
+export declare const NextRunsRequest: z.ZodObject<{
+  rule: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"daily">;
+    at: z.ZodString;
+  }, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"weekly">;
+    days: z.ZodArray<z.ZodEnum<{
+      mon: "mon";
+      tue: "tue";
+      wed: "wed";
+      thu: "thu";
+      fri: "fri";
+      sat: "sat";
+      sun: "sun";
+    }>>;
+    at: z.ZodString;
+  }, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"monthly">;
+    day: z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"last">]>;
+    at: z.ZodString;
+  }, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"cron">;
+    expr: z.ZodString;
+  }, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"once">;
+    at: z.ZodString;
+  }, z.core.$strip>], "kind">;
+  tz: z.ZodString;
+  count: z.ZodDefault<z.ZodNumber>;
+  from: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type NextRunsRequest = z.infer<typeof NextRunsRequest>;
+/** Upcoming fire times (epoch ms UTC), soonest first. */
+export declare const NextRunsResponse: z.ZodObject<{
+  runs: z.ZodArray<z.ZodNumber>;
+}, z.core.$strip>;
+export type NextRunsResponse = z.infer<typeof NextRunsResponse>;
+/** `pausedUntil` of a schedule paused until it is resumed (9999-12-31T23:59:59.999Z). */
+export declare const PAUSED_INDEFINITELY = 253402300799999;
+/** `POST /admin/schedules/:id/pause`. Without `until` the schedule stays paused until resumed. */
+export declare const SchedulePause: z.ZodObject<{
+  until: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type SchedulePause = z.infer<typeof SchedulePause>;

package/dist/contracts/schedules.js

@@ -0,0 +1,143 @@
+import { ClockTime, EpochMs, Id, JsonObject, TimeZone } from "./common.js";
+import { Recipients } from "./recipients.js";
+import { z } from "zod";
+// src/contracts/schedules.ts
+/** Weekday keys used by weekly rules. */
+const WEEKDAYS = [
+	"mon",
+	"tue",
+	"wed",
+	"thu",
+	"fri",
+	"sat",
+	"sun"
+];
+/** Zod enum of {@link WEEKDAYS}. */
+const Weekday = z.enum(WEEKDAYS);
+/** 5-field cron (minute hour day-of-month month day-of-week). Seconds and year fields are rejected. */
+const CronExpr = z.string().trim().max(120).refine((s) => s.split(/\s+/).length === 5, "schedule_rule_invalid");
+/** Local wall-clock date-time `YYYY-MM-DDTHH:MM`, read in the schedule's time zone. */
+const LocalDateTime = z.string().regex(/^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])T([01]\d|2[0-3]):[0-5]\d$/);
+/** When a schedule fires. All times are local to the schedule's `timezone`. */
+const ScheduleRule = z.discriminatedUnion("kind", [
+	z.object({
+		kind: z.literal("daily"),
+		at: ClockTime
+	}),
+	z.object({
+		kind: z.literal("weekly"),
+		days: z.array(Weekday).min(1).max(7).refine((d) => new Set(d).size === d.length, "duplicate day"),
+		at: ClockTime
+	}),
+	z.object({
+		kind: z.literal("monthly"),
+		day: z.union([z.number().int().min(1).max(31), z.literal("last")]),
+		at: ClockTime
+	}),
+	z.object({
+		kind: z.literal("cron"),
+		expr: CronExpr
+	}),
+	z.object({
+		kind: z.literal("once"),
+		at: LocalDateTime
+	})
+]);
+/** The `kind` values of {@link ScheduleRule}. */
+const SCHEDULE_RULE_KINDS = [
+	"daily",
+	"weekly",
+	"monthly",
+	"cron",
+	"once"
+];
+/** Zod enum of {@link SCHEDULE_RULE_KINDS}. */
+const ScheduleRuleKind = z.enum(SCHEDULE_RULE_KINDS);
+/** What to do with a slot found more than `missedGraceMin` late: `skip` it, or `run_once` (latest slot only). */
+const MISSED_POLICIES = ["skip", "run_once"];
+/** Zod enum of {@link MISSED_POLICIES}. */
+const MissedPolicy = z.enum(MISSED_POLICIES);
+/** Run outcome; `partial` = some deliveries queued before an error, `skipped` = missed-run policy skipped it. */
+const SCHEDULE_RUN_STATUSES = [
+	"running",
+	"done",
+	"partial",
+	"failed",
+	"skipped"
+];
+/** Zod enum of {@link SCHEDULE_RUN_STATUSES}. */
+const ScheduleRunStatus = z.enum(SCHEDULE_RUN_STATUSES);
+/** What started a run: the rule (`schedule`), or `run-now` (`manual`). */
+const SCHEDULE_RUN_TRIGGERS = ["schedule", "manual"];
+/** Zod enum of {@link SCHEDULE_RUN_TRIGGERS}. */
+const ScheduleRunTrigger = z.enum(SCHEDULE_RUN_TRIGGERS);
+/** A recurring templated send (`/admin/schedules`, permission `telegram.schedules.manage`). */
+const ScheduleDto = z.object({
+	id: Id,
+	name: z.string(),
+	rule: ScheduleRule,
+	/** IANA zone the rule is read in. */
+	timezone: z.string(),
+	templateId: Id,
+	params: JsonObject.nullable(),
+	recipients: Recipients,
+	/** True = run the provider per recipient user (exact redaction); false = once per audience role. */
+	personalize: z.boolean(),
+	missedPolicy: MissedPolicy,
+	/** Minutes a slot may be late and still run normally. */
+	missedGraceMin: z.number().int(),
+	enabled: z.boolean(),
+	/** Paused until this time (epoch ms UTC; {@link PAUSED_INDEFINITELY} = until resumed), or null. */
+	pausedUntil: EpochMs.nullable(),
+	/** Next planned slot (epoch ms UTC), or null when finished or disabled. */
+	nextRunAt: EpochMs.nullable(),
+	lastRunAt: EpochMs.nullable(),
+	lastStatus: ScheduleRunStatus.nullable(),
+	createdBy: z.string().nullable(),
+	createdAt: EpochMs,
+	updatedAt: EpochMs
+});
+/** `POST`/`PUT /admin/schedules` body (defaults: personalize, `run_once`, 30 min grace, enabled). */
+const ScheduleSave = z.object({
+	name: z.string().trim().min(1).max(120),
+	rule: ScheduleRule,
+	/** Defaults to the host's `settings.timezone`. */
+	timezone: TimeZone.optional(),
+	templateId: Id,
+	params: JsonObject.nullable().default(null),
+	recipients: Recipients,
+	personalize: z.boolean().default(true),
+	missedPolicy: MissedPolicy.default("run_once"),
+	missedGraceMin: z.number().int().min(0).max(1440).default(30),
+	enabled: z.boolean().default(true)
+});
+/** One schedule run (`GET /admin/schedules/:id/runs`). */
+const ScheduleRunDto = z.object({
+	id: Id,
+	scheduleId: Id,
+	/** Planned slot time this run is for (epoch ms UTC). */
+	slotAt: EpochMs,
+	trigger: ScheduleRunTrigger,
+	startedAt: EpochMs,
+	finishedAt: EpochMs.nullable(),
+	status: ScheduleRunStatus,
+	/** Delivery rows queued. */
+	deliveries: z.number().int().nonnegative(),
+	error: z.string().nullable(),
+	/** Template version rendered, or null if it failed before rendering. */
+	templateVersion: z.number().int().nullable()
+});
+/** `POST /admin/schedules/next-runs`. */
+const NextRunsRequest = z.object({
+	rule: ScheduleRule,
+	tz: TimeZone,
+	count: z.number().int().min(1).max(20).default(5),
+	from: EpochMs.optional()
+});
+/** Upcoming fire times (epoch ms UTC), soonest first. */
+const NextRunsResponse = z.object({ runs: z.array(EpochMs) });
+/** `pausedUntil` of a schedule paused until it is resumed (9999-12-31T23:59:59.999Z). */
+const PAUSED_INDEFINITELY = 0xe677d21fdbff;
+/** `POST /admin/schedules/:id/pause`. Without `until` the schedule stays paused until resumed. */
+const SchedulePause = z.object({ until: EpochMs.optional() });
+export { CronExpr, LocalDateTime, MISSED_POLICIES, MissedPolicy, NextRunsRequest, NextRunsResponse, PAUSED_INDEFINITELY, SCHEDULE_RULE_KINDS, SCHEDULE_RUN_STATUSES, SCHEDULE_RUN_TRIGGERS, ScheduleDto, SchedulePause, ScheduleRule, ScheduleRuleKind, ScheduleRunDto, ScheduleRunStatus, ScheduleRunTrigger, ScheduleSave, WEEKDAYS, Weekday };