@diagonal-hq/cli 0.2.0 → 0.4.0

package/dist/fields.generated.d.ts

@@ -371,7 +371,7 @@ export type RelationInverse = {
   settings?: Omit<RelationFieldSettings, 'inverse'> & { "max_connections"?: number | null };
 };
 
-/** A relation names its target resource by id or slug. The type defaults to `belongs_to`. */
+/** A relation names its target resource by slug, as `Resources.<Name>`. The type defaults to `belongs_to`. */
 export type RelationFieldOptions = Omit<BaseFieldOptions<RelationFieldSettings>, 'settings'> & { resource: string } & (
   | { type?: "belongs_to"; settings?: RelationFieldSettings }
   | { type: "belongs_to_many"; settings?: RelationFieldSettings & { "max_connections"?: number | null } }

package/dist/index.d.ts

@@ -76,13 +76,8 @@ export type ResourceDataApi = {
 export type ResourceDefinition<
   TFields extends Record<string, FieldDefinition> = Record<string, FieldDefinition>
 > = {
-  /**
-   * A lowercase UUID v7, for example '0199f000-0000-7000-8000-000000000001'.
-   * `diagonal check` suggests a new one when the id is not v7. Keep it
-   * stable: records and workflows refer to it.
-   */
-  id: string;
-  slug: string;
+  /** Only a platform resource reference sets `platform`. */
+  platform?: never;
   name: string;
   singularName: string;
   displayField?: Extract<keyof TFields, string>;
@@ -112,16 +107,22 @@ export type ResourceDefinition<
   capabilities?: ResourceCapabilities<TFields>;
 };
 
+/**
+ * A resource that the platform provisions and owns, such as the roles. The
+ * file gives it a `Resources` entry. The deploy does not change it.
+ */
+export type PlatformResourceDefinition = { platform: true };
+
 export declare function defineResource<const TFields extends Record<string, FieldDefinition>>(
-  resource: ResourceDefinition<TFields>
-): ResourceDefinition<TFields>;
+  resource: ResourceDefinition<TFields> | PlatformResourceDefinition
+): ResourceDefinition<TFields> | PlatformResourceDefinition;
 
 /** A TipTap document whose mentions resolve against the page's bound records. */
 export type PageMetaResolver = { readonly type: string; readonly [key: string]: unknown };
 
 export type PageRouteParam = {
-  /** The slug or id of the resource whose record the parameter names. */
-  resource: string;
+  /** The resource whose record the parameter names, as `Resources.<Name>`. */
+  resource: ResourceReference;
   /** The field the parameter matches. Defaults to the record id. */
   lookupField?: string | null;
   /** Relation fields to load with the record. */
@@ -133,8 +134,8 @@ export type PageAuthorizer =
   | null
   | 'authenticated'
   | {
-      /** The slug or id of the resource whose signed-in records may view the page. */
-      resource?: string | null;
+      /** The resource whose signed-in records may view the page, as `Resources.<Name>`. */
+      resource?: ResourceReference | null;
       /** Permission ids. A viewer needs any one of them. */
       permissions?: readonly string[];
     };
@@ -180,7 +181,11 @@ export type NavigationDefinition = { id: string; items: readonly NavigationItem[
 
 export declare function defineNavigation<const T extends NavigationDefinition>(navigation: T): T;
 
-/** The slug, name, or id of a resource. */
+/**
+ * The slug of a resource: its file name in `resources/`. Use `Resources.<Name>`
+ * from `@app/generated/resources`, which `diagonal check` writes, so the editor
+ * and the build catch a wrong name. A slug string builds with a warning.
+ */
 export type ResourceReference = string;
 
 export type WorkflowRunAs =

package/dist/sdk-contract.d.ts

@@ -2296,9 +2296,15 @@ type SdkSendResolvedNotificationHandle = Omit<SdkSendEmailHandle, 'send' | 'data
 
 type SdkUpcomingNotification = {
   id: string;
+  revision: number;
+  idempotency_key: string | null;
+  computed_at: string | null;
+  scheduled_at_override: string | null;
+  changed_by_resource_id: string | null;
+  changed_by_record_id: string | null;
   notification_type_name: string;
-  scheduled_at: string;
-  status: 'scheduled' | 'failed';
+  scheduled_at: string | null;
+  status: 'draft' | 'scheduled' | 'failed';
   is_one_off: boolean;
   is_paused: boolean;
   /** Held occurrences do not send until they are resumed. */
@@ -2306,6 +2312,8 @@ type SdkUpcomingNotification = {
   can_cancel: boolean;
   can_edit: boolean;
   can_reschedule: boolean;
+  can_save: boolean;
+  can_schedule: boolean;
   can_send_now: boolean;
   can_hold: boolean;
   can_resume: boolean;
@@ -2318,7 +2326,7 @@ type SdkScheduledNotificationContent = {
 };
 
 type SdkScheduledNotificationDetail = Omit<SdkUpcomingNotification, 'status'> & {
-  status: 'scheduled' | 'failed' | 'queued' | 'cancelled' | 'expired';
+  status: 'draft' | 'scheduled' | 'failed' | 'queued' | 'cancelled' | 'expired';
   notification_type_id: string;
   notification_template_id: string;
   recipient: SdkNotificationRecipient;
@@ -2328,13 +2336,16 @@ type SdkScheduledNotificationDetail = Omit<SdkUpcomingNotification, 'status'> &
 };
 
 type SdkScheduledNotificationEdits = {
+  expected_revision: number;
   recipient?: SdkNotificationRecipient;
   /** Omit to retain content. Null restores the shared template. Use raw content from ScheduledNotificationComposer, not resolved NotificationComposer output. */
   content_override?: SdkScheduledNotificationContent | null;
 };
 
 type SdkUpdateScheduledNotificationInput = SdkScheduledNotificationEdits & {
-  /** One-offs only. Future ISO datetime with Z or an explicit offset. */
+  /** Required with scheduled_at to release a saved draft. */
+  transition?: 'schedule';
+  /** Explicit send-time override. Future ISO datetime with Z or an explicit offset. */
   scheduled_at?: string;
 };
 
@@ -2351,14 +2362,15 @@ type SdkUpdateScheduledNotificationHandle = {
 
 type SdkScheduledNotificationResult = {
   id: string;
-  status: 'scheduled';
+  revision: number;
+  status: 'draft' | 'scheduled' | 'failed' | 'cancelled' | 'queued' | 'expired';
 };
 
 type SdkSendScheduledNotificationNowHandle = {
   /** Applies edits and queues this occurrence once. Queued does not mean delivered. Never retries automatically. */
   sendNow: (
     id: string,
-    input?: SdkScheduledNotificationEdits
+    input: SdkScheduledNotificationEdits
   ) => Promise<{ id: string; status: 'queued' }>;
   isPending: boolean;
   error: ApiError | null;
@@ -2526,8 +2538,8 @@ type SdkNotificationHistoryItem = {
   /** Saved name for sent rows; the current name, or a deleted placeholder, otherwise. */
   notification_type_name: string;
   notification_template_name: string;
-  /** Send time for scheduled rows; preparation time for sent rows. ISO 8601. */
-  occurred_at: string;
+  /** Send time for scheduled rows; preparation time for sent rows. ISO 8601, or null for unscheduled drafts. */
+  occurred_at: string | null;
   source_kind: SdkNotificationSourceKind;
   /** Schedule or workflow name. Null without the `manage_notifications` permission. */
   source_name: string | null;
@@ -2652,22 +2664,29 @@ type SdkUpcomingNotificationsOptions = {
   enabled?: boolean;
 };
 
-type SdkScheduleNotificationInput = {
-  notification_type_id: string;
-  notification_template_id: string;
-  recipient: SdkNotificationRecipient;
-  variables: Record<string, any>;
-  /** Future ISO 8601 timestamp with Z or an explicit UTC offset. */
-  scheduled_at: string;
-  /**
-   * A repeated key resolves with the notification that first used it. At send time, the key
-   * also stops delivery when a send or bulk item already used it.
-   */
-  idempotency_key?: string;
-};
+type SdkScheduleNotificationInput =
+  | ({
+      notification_type_id: string;
+      notification_template_id: string;
+      recipient: SdkNotificationRecipient;
+      variables: Record<string, any>;
+      content_override?: SdkScheduledNotificationContent | null;
+      idempotency_key?: string;
+    } & (
+      | { status: 'draft'; idempotency_key: string; scheduled_at?: never }
+      | { status?: 'scheduled'; scheduled_at: string }
+    ))
+  | {
+      notification_schedule_id: string;
+      source_record_id: string;
+      stage_id: string;
+      status: 'draft';
+      content_override?: SdkScheduledNotificationContent | null;
+    };
 
 type SdkCancelledNotificationResult = {
   id: string;
+  revision: number;
   status: 'cancelled';
 };
 
@@ -2681,7 +2700,7 @@ type SdkScheduleNotificationHandle = {
 
 type SdkCancelScheduledNotificationHandle = {
   /** Rejects with ApiError on failure, including 409 once delivery has started. */
-  cancel: (id: string) => Promise<SdkCancelledNotificationResult>;
+  cancel: (id: string, expectedRevision: number) => Promise<SdkCancelledNotificationResult>;
   isPending: boolean;
   error: ApiError | null;
   reset: () => void;
@@ -2689,6 +2708,7 @@ type SdkCancelScheduledNotificationHandle = {
 
 type SdkHeldNotificationResult = {
   id: string;
+  revision: number;
   status: 'scheduled' | 'failed';
   is_held: boolean;
   scheduled_at: string;
@@ -2696,7 +2716,7 @@ type SdkHeldNotificationResult = {
 
 type SdkHoldScheduledNotificationHandle = {
   /** Rejects with ApiError on failure, including 409 once delivery has started. */
-  hold: (id: string) => Promise<SdkHeldNotificationResult>;
+  hold: (id: string, expectedRevision: number) => Promise<SdkHeldNotificationResult>;
   isPending: boolean;
   error: ApiError | null;
   reset: () => void;
@@ -2707,7 +2727,11 @@ type SdkResumeScheduledNotificationHandle = {
    * Pass a future ISO `scheduledAt` with Z or an offset to send at a new time. It is required
    * when the saved time passed during the hold. Rejects with ApiError on failure.
    */
-  resume: (id: string, scheduledAt?: string) => Promise<SdkHeldNotificationResult>;
+  resume: (
+    id: string,
+    expectedRevision: number,
+    scheduledAt?: string
+  ) => Promise<SdkHeldNotificationResult>;
   isPending: boolean;
   error: ApiError | null;
   reset: () => void;
@@ -7190,6 +7214,9 @@ type SdkHooks = {
    * scheduled_at must be a future ISO timestamp with Z or an offset; convert local input
    * with new Date(value).toISOString(). Template values resolve again at send preparation.
    * Success refreshes upcoming-notification queries. The promise rejects with ApiError.
+   * Use status: "draft" without scheduled_at to prepare an unscheduled draft. One-off drafts
+   * require idempotency_key. Generated drafts use notification_schedule_id, source_record_id,
+   * and stage_id. Saving a draft never releases it; use Send or transition: "schedule".
    * An `idempotency_key` makes a repeated schedule call return the first scheduled
    * notification unchanged. At send time the key also stops delivery when a send, bulk item,
    * or workflow already used it, so a manual send and a scheduled send of one notice reach the
@@ -7207,7 +7234,7 @@ type SdkHooks = {
    * or expired items return 409. Success refreshes upcoming lists. Rejects with ApiError.
    * @example
    * const cancellation = Sdk.hooks.useCancelScheduledNotification();
-   * await cancellation.cancel(notification.id);
+   * await cancellation.cancel(notification.id, notification.revision);
    */
   useCancelScheduledNotification(): SdkCancelScheduledNotificationHandle;
 
@@ -7217,17 +7244,17 @@ type SdkHooks = {
    * as cancel. Repeated holds succeed. Success refreshes upcoming lists. Rejects with ApiError.
    * @example
    * const hold = Sdk.hooks.useHoldScheduledNotification();
-   * await hold.hold(notification.id);
+   * await hold.hold(notification.id, notification.revision);
    */
   useHoldScheduledNotification(): SdkHoldScheduledNotificationHandle;
 
   /**
    * Resume a held occurrence so it sends once at its time. When that time passed during the
    * hold, pass a new future time; the old time never sends late. A generated occurrence keeps
-   * the new time until its schedule date changes. Rejects with ApiError.
+   * the explicit time across schedule date changes. Rejects with ApiError.
    * @example
    * const resume = Sdk.hooks.useResumeScheduledNotification();
-   * await resume.resume(notification.id, new Date(value).toISOString());
+   * await resume.resume(notification.id, notification.revision, new Date(value).toISOString());
    */
   useResumeScheduledNotification(): SdkResumeScheduledNotificationHandle;
 
@@ -7243,22 +7270,22 @@ type SdkHooks = {
   ): SdkApiHandle<SdkScheduledNotificationDetail>;
 
   /**
-   * Edit a scheduled or failed occurrence. Only one-offs can change scheduled_at.
+   * Edit a draft, scheduled, or failed occurrence. Pass its expected_revision.
    * A null content_override restores the template. Failed preparation recovers only
    * after successful resolution. Refreshes detail and all upcoming record lists.
    * @example
    * const editing = Sdk.hooks.useUpdateScheduledNotification();
-   * await editing.update(id, { content_override: null });
+   * await editing.update(id, { expected_revision: notification.revision, content_override: null });
    */
   useUpdateScheduledNotification(): SdkUpdateScheduledNotificationHandle;
 
   /**
-   * Apply edits and send the same scheduled or failed occurrence now, including
+   * Apply edits and send the same draft, scheduled, or failed occurrence now, including
    * paused occurrences. The original time cannot send it again. Rejects terminal
    * items with 409. Refreshes detail, upcoming lists, and email history.
    * @example
    * const sending = Sdk.hooks.useSendScheduledNotificationNow();
-   * await sending.sendNow(id);
+   * await sending.sendNow(id, { expected_revision: notification.revision });
    */
   useSendScheduledNotificationNow(): SdkSendScheduledNotificationNowHandle;
 
@@ -12698,7 +12725,7 @@ type ScheduledNotificationComposerProps = {
   /** The occurrence to open, such as an id from useUpcomingNotifications. */
   scheduledNotificationId: string;
   /** Edited raw content, ready to save as content_override. Null while nothing changed, and when the occurrence cannot be edited. */
-  onChange: (content: SdkScheduledNotificationContent | null) => void;
+  onChange: (content: SdkScheduledNotificationContent | null, expectedRevision?: number) => void;
   /** Preview for an unsaved recipient change instead of the saved recipient. */
   recipient?: SdkNotificationRecipient;
   /** Omit to allow every text layout field. An empty array locks every layout field. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diagonal-hq/cli",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "The diagonal CLI and the configuration helpers for file-based Diagonal workspaces.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {