@leaflow/sdk 0.107.0 → 0.109.0

package/dist/notification/v1/generated/models.d.ts

@@ -0,0 +1,688 @@
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * Leaflow Notification API
+ * Read the notifications this platform has sent you, and choose where each kind of notification
+ * is delivered.
+ *
+ * Every service on the platform reports events here rather than contacting you directly. This
+ * API is the single place where those events are read, and the single place where delivery is
+ * configured.
+ *
+ * ## Authentication
+ *
+ * Every request carries a scoped token; see the `bearerAuth` security scheme.
+ *
+ * **Neither the path nor the headers carry a `project_id`**: the current project is determined by
+ * the token. Listing operations return everything addressed to you across every project by
+ * default, because a notification is addressed to a person rather than to a project; pass
+ * `scope=current_project` to narrow the result to the project in the token.
+ *
+ * ## Conventions
+ *
+ * - **Notifications are typed, and the type determines who receives it.** A type such as
+ *   `compute.instance.provisioned` is addressed to whoever created the instance, while
+ *   `monitoring.alert.raised` is addressed to every member of the project. The full catalogue is
+ *   available from `GET /api/v1/notification-types` and is stable: a type identifier is never
+ *   reused for a different event.
+ * - **Text is rendered at read time from the language on your preferences.** Changing the
+ *   language changes the text of everything already in the inbox. Messages already delivered by
+ *   email or to an outbound channel are not rewritten, because they have already been sent.
+ * - **Times inside rendered text are stated in UTC and say so.** There is no time zone setting.
+ *   Clients that can determine the reader's time zone should present `created_at`, `occurred_at`
+ *   and the timestamps in `params` — all of which are RFC 3339 — in local time instead. Email
+ *   cannot do this, which is why the text it carries is explicit about being UTC.
+ * - **Some types must reach you, and those cannot be muted or removed from email.** They are
+ *   marked `mandatory` in the catalogue: types you would only find out about by signing in, when
+ *   not finding out costs you something — a suspension, a deletion, a credential that expires.
+ *   Everything else about them is still configurable, including adding channels of your own.
+ * - **Deleting a preference restores the default; it does not turn the type off.** To stop
+ *   receiving a type, set `muted` on it.
+ * - **Outbound channels deliver nothing until they are verified.** Registering a channel does not
+ *   contact it. Verification is a separate operation that sends one message, and only a channel
+ *   that has acknowledged it receives anything afterwards.
+ * - **Channel endpoints are never returned.** No operation, including the one that registers
+ *   them, returns the address that was submitted. A channel entered incorrectly must be deleted
+ *   and registered again.
+ *
+ * ## Rate and volume
+ *
+ * Delivery to outbound channels is limited per channel, and bursts of alerts about one server are
+ * summarised rather than sent individually. Nothing is summarised in the inbox: it always holds
+ * every notification. A notification that was summarised or suppressed is still readable here.
+ *
+ * ## One-time credentials
+ *
+ * Some notifications carry a reference to a credential rather than the credential itself — the
+ * initial password of a newly created instance, for example. That credential is readable exactly
+ * once, expires on its own, and is destroyed as soon as it has been read. Requesting it a second
+ * time returns `CREDENTIAL_TICKET_CONSUMED`.
+ * OpenAPI spec version: 1.0.0
+ */
+/**
+ * What a given `code` carries alongside the message. The keys depend on the code,
+ * and a client that does not recognise one ignores it.
+ */
+export type ErrorMeta = {
+    [key: string]: unknown;
+};
+export interface Error {
+    code?: string;
+    message: string;
+    /**
+     * What a given `code` carries alongside the message. The keys depend on the code,
+     * and a client that does not recognise one ignores it.
+     */
+    meta?: ErrorMeta;
+    status: number;
+}
+/**
+ * `all` covers every project you belong to as well as notifications that belong to no
+ * project. `current_project` covers only the project in the token.
+ */
+export type NotificationScope = (typeof NotificationScope)[keyof typeof NotificationScope];
+export declare const NotificationScope: {
+    readonly all: "all";
+    readonly current_project: "current_project";
+};
+/**
+ * How much attention a notification asks for. It is assigned by the type and by the event,
+ * not by the recipient.
+ *
+ * `critical` announces something that is either irreversible or actively costing the
+ * recipient something.
+ */
+export type NotificationSeverity = (typeof NotificationSeverity)[keyof typeof NotificationSeverity];
+export declare const NotificationSeverity: {
+    readonly info: "info";
+    readonly warning: "warning";
+    readonly error: "error";
+    readonly critical: "critical";
+};
+/**
+ * `notification` is addressed to you. `announcement` was published to the whole platform and
+ * appears in everyone's inbox.
+ */
+export type NotificationKind = (typeof NotificationKind)[keyof typeof NotificationKind];
+export declare const NotificationKind: {
+    readonly notification: "notification";
+    readonly announcement: "announcement";
+};
+/**
+ * Where a notification is delivered.
+ *
+ * `inbox` is this API. `email` is the address on your preferences. `webhook` covers every
+ * outbound channel you have registered — the message is shaped for each one.
+ */
+export type NotificationChannel = (typeof NotificationChannel)[keyof typeof NotificationChannel];
+export declare const NotificationChannel: {
+    readonly inbox: "inbox";
+    readonly email: "email";
+    readonly webhook: "webhook";
+};
+/**
+ * `user` is yours alone. `project` is shared with everyone in the project and requires
+ * `notification:channels.manage` to register or delete.
+ */
+export type ChannelScope = (typeof ChannelScope)[keyof typeof ChannelScope];
+export declare const ChannelScope: {
+    readonly user: "user";
+    readonly project: "project";
+};
+/**
+ * The kind of endpoint, which determines both how the message is shaped and what the
+ * endpoint is.
+ *
+ * `lark_webhook` and `wecom_webhook` are group robot webhook URLs and receive a card.
+ * `bark` is a Bark server URL including the device key and receives a short line of text.
+ * `generic_webhook` receives a JSON document and is the option for anything else.
+ */
+export type ChannelKind = (typeof ChannelKind)[keyof typeof ChannelKind];
+export declare const ChannelKind: {
+    readonly lark_webhook: "lark_webhook";
+    readonly wecom_webhook: "wecom_webhook";
+    readonly bark: "bark";
+    readonly generic_webhook: "generic_webhook";
+};
+/**
+ * Who a type is addressed to. It is a property of the type, so it is the same for every
+ * occurrence.
+ *
+ * `explicit` is whoever the reporting service names, usually the person who asked for the
+ * action. `account` is one person, independently of any project. `address` is an email
+ * address belonging to someone who may not have an account yet. `broadcast` is everyone.
+ */
+export type NotificationAudience = (typeof NotificationAudience)[keyof typeof NotificationAudience];
+export declare const NotificationAudience: {
+    readonly explicit: "explicit";
+    readonly account: "account";
+    readonly address: "address";
+    readonly project_members: "project_members";
+    readonly project_owner: "project_owner";
+    readonly project_admins: "project_admins";
+    readonly broadcast: "broadcast";
+};
+/**
+ * One announcement, with its text in the language on your preferences.
+ */
+export interface AnnouncementResource {
+    id: string;
+    title: string;
+    /** The text as a fragment of HTML, same rules as a notification body */
+    body: string;
+    severity: NotificationSeverity;
+    /** You cannot dismiss this one. It is a property of the announcement rather than a second type, because what the operator judges when writing it is "is this important enough to push", and that is the question this asks. */
+    critical: boolean;
+    published_at: string;
+    /**
+     * When it drops out of this list; null means it stays
+     * @nullable
+     */
+    expires_at?: string | null;
+    /**
+     * When you read it; null means you have not
+     * @nullable
+     */
+    read_at?: string | null;
+}
+export interface AnnouncementListResource {
+    items: AnnouncementResource[];
+    /** How many of them you have not read */
+    unread: number;
+}
+export interface AnnouncementReadResultResource {
+    /** How many this call changed; already-read ones are not counted */
+    marked: number;
+}
+/**
+ * The facts the text was rendered from, for clients that want to link to the resource the
+ * notification is about. The names are documented per type in the catalogue.
+ */
+export type NotificationResourceParams = {
+    [key: string]: unknown;
+};
+/**
+ * One notification, with its text rendered in the language on your preferences at the moment
+ * it was read.
+ */
+export interface NotificationResource {
+    /**
+     * When you archived it; null if you did not
+     * @nullable
+     */
+    archived_at: string | null;
+    /** The text, as a fragment of HTML. Contains formatting and links, no scripts and no styles */
+    body: string;
+    /** The same text without markup, for clients that cannot render HTML */
+    body_text: string;
+    created_at: string;
+    id: string;
+    kind: NotificationKind;
+    /** The language this text was rendered in */
+    locale: string;
+    /** When the event itself happened, which precedes created_at */
+    occurred_at: string;
+    /**
+     * The facts the text was rendered from, for clients that want to link to the resource the
+     * notification is about. The names are documented per type in the catalogue.
+     */
+    params: NotificationResourceParams;
+    /**
+     * The project the event belongs to; null for events that belong to no project
+     * @nullable
+     */
+    project_id: string | null;
+    /**
+     * When you read it; null if you have not
+     * @nullable
+     */
+    read_at: string | null;
+    severity: NotificationSeverity;
+    /** A single line, without markup */
+    title: string;
+    /** The type identifier; empty for announcements, which have no type */
+    type: string;
+}
+export interface LengthAwarePageNotificationResource {
+    /** The contents of this page */
+    items: NotificationResource[];
+    /** Maximum items per page, echoing the value in the request */
+    limit: number;
+    /** Items skipped, echoing the value in the request */
+    offset: number;
+    /** Total number of matching items, not only those in this page */
+    total: number;
+    /** Unread notifications in the same scope, not only in this page */
+    unread_count: number;
+}
+export interface UnreadCountResource {
+    unread_count: number;
+}
+/**
+ * An empty list marks everything currently unread as read.
+ */
+export interface MarkNotificationsReadRequestBody {
+    /** @maxItems 500 */
+    notification_ids: string[];
+}
+/**
+ * One entry in the catalogue of everything the platform can notify about.
+ */
+export interface NotificationTypeDescriptor {
+    audience: NotificationAudience;
+    /** The channels this type may be delivered on. Configuring any other channel is rejected */
+    available_channels: NotificationChannel[];
+    /** The channels this type is delivered on when nothing has been configured */
+    default_channels: NotificationChannel[];
+    /**
+     * True when this type must reach you: it cannot be muted, and email cannot be removed
+     * from its channels. Everything else about it is still configurable
+     */
+    mandatory: boolean;
+    /** The names of the facts this type carries, as they appear on NotificationResource.params */
+    params: string[];
+    /** The service that reports this type */
+    service: string;
+    severity: NotificationSeverity;
+    /**
+     * A short name for this type, in the reader's language — what a settings screen puts on
+     * the row. It is not the subject line of the notification itself: a subject says what
+     * happened this time and carries the ticket number, while this names the kind of thing.
+     */
+    title: string;
+    type: string;
+}
+export interface NotificationTypeListResponseBody {
+    items: NotificationTypeDescriptor[];
+}
+export interface PreferencesResource {
+    /** Where email is delivered right now, which is the account address unless a verified override replaces it */
+    email_address: string;
+    /**
+     * The address email goes to instead of the account address; null when the account address
+     * is used. Only ever an address that was confirmed by code
+     * @nullable
+     */
+    email_override: string | null;
+    /**
+     * An address waiting to be confirmed; null when nothing is waiting. It receives nothing but
+     * the code, and the address in `email_override` keeps being used until this one is
+     * confirmed
+     * @nullable
+     */
+    email_override_pending: string | null;
+    /**
+     * When the code last sent to the pending address stops working; null when no code is
+     * outstanding, in which case a new one has to be sent before it can be confirmed
+     * @nullable
+     */
+    email_override_pending_expires_at: string | null;
+    /**
+     * When the address in `email_override` was confirmed; null when there is no override
+     * @nullable
+     */
+    email_override_verified_at: string | null;
+    /** The language notifications are written in, as an IETF language tag */
+    locale: string;
+}
+/**
+ * Fields that are omitted are left alone.
+ */
+export interface UpdatePreferencesRequestBody {
+    /**
+     * An address to receive email instead of the account address. It is stored as pending and
+     * receives nothing until it is confirmed by code, so the address in use does not change
+     * here. Null clears both the pending address and the one in use, returning delivery to
+     * the account address
+     * @maxLength 320
+     * @nullable
+     */
+    email_override?: string | null;
+    /**
+     * An IETF language tag. A language that is not supported is rejected rather than approximated
+     * @minLength 2
+     * @maxLength 16
+     */
+    locale?: string;
+}
+/**
+ * What was sent, and when the next one may be asked for.
+ */
+export interface EmailOverrideCodeResource {
+    /** Where the code went. It is the pending address, echoed so a client can show it */
+    address: string;
+    /** When this code stops working */
+    expires_at: string;
+    /**
+     * The earliest another code may be asked for. Asking sooner is refused rather than
+     * silently ignored, so a client can show the wait instead of a failure
+     */
+    resend_available_at: string;
+}
+export interface ConfirmEmailOverrideRequestBody {
+    /**
+     * The code from the email, exactly as it appears there
+     * @minLength 4
+     * @maxLength 16
+     */
+    code: string;
+}
+export interface TypePreferenceResource {
+    /** Where this type is delivered */
+    channels: NotificationChannel[];
+    /** True when nothing has been configured and these are the defaults from the catalogue */
+    inherited: boolean;
+    /** True when this type cannot be muted and email cannot be removed from it */
+    mandatory: boolean;
+    /**
+     * Deliver only at or above this severity. Null delivers every severity. It applies to the
+     * channels named here and not to the inbox, which always holds everything
+     */
+    min_severity: NotificationSeverity | null;
+    /** True when this type is not delivered anywhere except the inbox */
+    muted: boolean;
+    /**
+     * The project this preference applies to; null when it applies to every project
+     * @nullable
+     */
+    project_id: string | null;
+    type: string;
+}
+export interface TypePreferenceListResponseBody {
+    items: TypePreferenceResource[];
+}
+/**
+ * States how this type should be delivered, replacing whatever was configured before.
+ */
+export interface UpdateTypePreferenceRequestBody {
+    /**
+     * Where to deliver this type, beyond the inbox. An empty list delivers to the inbox only.
+     * `inbox` may be listed and is accepted, but has no effect: every notification is in the
+     * inbox whatever this says
+     * @maxItems 8
+     */
+    channels: NotificationChannel[];
+    /** Deliver only at or above this severity. Null delivers every severity */
+    min_severity?: NotificationSeverity | null;
+    /** Stop delivering this type anywhere except the inbox */
+    muted?: boolean;
+}
+/**
+ * A registered outbound channel. The endpoint itself is never included.
+ */
+export interface ChannelResource {
+    channel_scope: ChannelScope;
+    /** Deliveries that have failed in a row. Reset by a success, and by re-enabling the channel */
+    consecutive_failures: number;
+    created_at: string;
+    /**
+     * When the channel was disabled after repeated failures; null if it is enabled
+     * @nullable
+     */
+    disabled_at: string | null;
+    /**
+     * Why it was disabled; null if it is enabled
+     * @nullable
+     */
+    disabled_reason: string | null;
+    id: string;
+    kind: ChannelKind;
+    /**
+     * Why the most recent attempt failed, in the endpoint's own wording; null if the most recent attempt succeeded
+     * @nullable
+     */
+    last_error: string | null;
+    /** @nullable */
+    last_failure_at: string | null;
+    /** @nullable */
+    last_success_at: string | null;
+    name: string;
+    /**
+     * The project this channel is shared with; null for a channel of scope user
+     * @nullable
+     */
+    project_id: string | null;
+    /** A partially masked fragment of the endpoint, for visual identification only */
+    redacted: string;
+    updated_at: string;
+    /**
+     * When the endpoint last acknowledged a verification message; null while it never has, during which the channel is skipped
+     * @nullable
+     */
+    verified_at: string | null;
+}
+export interface ChannelListResponseBody {
+    items: ChannelResource[];
+}
+export interface CreateChannelRequestBody {
+    channel_scope: ChannelScope;
+    /**
+     * The address messages are sent to. It must be an https URL reachable over the public
+     * internet.
+     *
+     * For `lark_webhook` and `wecom_webhook` this is the group robot webhook URL. For `bark`
+     * it is the push URL including the device key, such as
+     * `https://api.day.app/your-device-key`. For `generic_webhook` it is any endpoint
+     * accepting a JSON POST.
+     * @minLength 1
+     * @maxLength 2048
+     */
+    endpoint: string;
+    kind: ChannelKind;
+    /**
+     * A display name for this channel
+     * @minLength 1
+     * @maxLength 128
+     */
+    name: string;
+    /**
+     * The signing secret, where the endpoint has one. It is required for a Lark group robot
+     * configured with signature verification, and optional for `generic_webhook`, where it
+     * signs the request so the receiver can confirm the message came from this platform.
+     *
+     * It is not returned by any operation.
+     * @maxLength 512
+     */
+    secret?: string;
+}
+/**
+ * Fields that are omitted are left alone.
+ */
+export interface UpdateChannelRequestBody {
+    /** Set true to re-enable a channel that was disabled after repeated failures, clearing the failure count */
+    enabled?: boolean;
+    /**
+     * @minLength 1
+     * @maxLength 128
+     */
+    name?: string;
+}
+/**
+ * What the credential belongs to.
+ */
+export type CredentialSubjectKind = (typeof CredentialSubjectKind)[keyof typeof CredentialSubjectKind];
+export declare const CredentialSubjectKind: {
+    readonly compute_instance: "compute_instance";
+};
+/**
+ * A one-time credential, described without being consumed.
+ */
+export interface CredentialTicketResource {
+    /**
+     * True when the credential can still be revealed. False once it has been revealed, has
+     * expired, or was withdrawn — in all three cases it is already destroyed
+     */
+    available: boolean;
+    /** After this moment the credential is destroyed whether or not it was read */
+    expires_at: string;
+    id: string;
+    /**
+     * When it was revealed; null if it has not been
+     * @nullable
+     */
+    revealed_at: string | null;
+    /**
+     * When the service that issued it withdrew it; null if it did not
+     * @nullable
+     */
+    revoked_at: string | null;
+    /** The resource the credential belongs to */
+    subject_id: string;
+    subject_kind: CredentialSubjectKind;
+}
+/**
+ * The credential itself. This shape is returned by exactly one operation, and that operation
+ * succeeds at most once per ticket.
+ */
+export interface RevealedCredentialResource {
+    revealed_at: string;
+    /** The credential. It is destroyed as this response is produced and cannot be obtained again */
+    secret: string;
+    subject_id: string;
+    subject_kind: CredentialSubjectKind;
+    /**
+     * The account the credential belongs to, where the resource has one; null otherwise
+     * @nullable
+     */
+    username: string | null;
+}
+/**
+ * Everything needed to open a realtime connection. The connection speaks the Pusher channels
+ * protocol, so any client library for it works.
+ */
+export interface RealtimeConnectionResource {
+    /** The path a client posts to while subscribing, relative to this API */
+    auth_path: string;
+    /** The cluster name some client libraries require; empty when the deployment does not use one */
+    cluster: string;
+    /** False when realtime delivery is not configured in this deployment. Every other field is empty and clients should not attempt to connect */
+    enabled: boolean;
+    host: string;
+    /** The application key, which is public and identifies the deployment rather than the caller */
+    key: string;
+    port: number;
+    /**
+     * The channel carrying announcements. It is public: subscribing to it needs no
+     * authorization, because an announcement is addressed to everybody. The events on it
+     * carry an identifier and nothing else, so a client fetches the list and sees the
+     * announcements it is entitled to
+     */
+    announcements_channel: string;
+    /** The channel carrying events about the project in the token; empty when the token names no project */
+    project_channel: string;
+    /** Whether to connect over TLS */
+    secure: boolean;
+    /** The channel carrying events addressed to you */
+    user_channel: string;
+}
+export interface AuthorizeRealtimeChannelRequestBody {
+    /**
+     * The channel being subscribed to
+     * @minLength 1
+     * @maxLength 255
+     */
+    channel_name: string;
+    /**
+     * The connection identifier the realtime server assigned to this client
+     * @minLength 1
+     * @maxLength 128
+     */
+    socket_id: string;
+}
+export interface RealtimeAuthResource {
+    /** The authorization token for this subscription, passed back to the realtime server by the client library */
+    auth: string;
+}
+/**
+ * Pagination metadata for stable numbered pages. total_count is returned only when the operation can determine it without an unbounded scan.
+ */
+export interface OffsetPagination {
+    /** @minimum 1 */
+    page: number;
+    /** @minimum 1 */
+    page_size: number;
+    /** @minimum 0 */
+    total_count?: number;
+}
+/**
+ * Pagination metadata for keyset traversal. Pass next_cursor as cursor to read the following page; null means there is no following page.
+ */
+export interface CursorPagination {
+    /** @minimum 1 */
+    page_size: number;
+    /** @nullable */
+    next_cursor?: string | null;
+}
+/**
+ * Apply to this project alone; omit to apply to every project
+ */
+export type PreferenceProjectIdParameter = string;
+export type ListNotificationsParams = {
+    /**
+     * Items returned in this page. Defaults to 50; at most 200.
+     * @minimum 1
+     * @maximum 200
+     */
+    limit?: number;
+    /**
+     * Items to skip. Defaults to 0; at most 10000.
+     * @minimum 0
+     * @maximum 10000
+     */
+    offset?: number;
+    /**
+     * Which projects to include; defaults to every project
+     */
+    scope?: NotificationScope;
+    /**
+     * Return only notifications of this type; omit for all types
+     * @maxLength 128
+     */
+    type?: string;
+    /**
+     * Return only notifications at or above this severity; omit for all severities
+     */
+    min_severity?: NotificationSeverity;
+    /**
+     * Restrict to unread, to read, or to neither; omit for both
+     */
+    read?: boolean;
+    /**
+     * Include archived notifications; they are excluded by default
+     */
+    include_archived?: boolean;
+};
+export type CountUnreadNotificationsParams = {
+    /**
+     * Which projects to include; defaults to every project
+     */
+    scope?: NotificationScope;
+};
+export type ListTypePreferencesParams = {
+    /**
+     * Return preferences for this project in addition to the account-wide ones
+     */
+    project_id?: string;
+};
+export type UpdateTypePreferenceParams = {
+    /**
+     * Apply to this project alone; omit to apply to every project
+     */
+    project_id?: PreferenceProjectIdParameter;
+};
+export type DeleteTypePreferenceParams = {
+    /**
+     * Apply to this project alone; omit to apply to every project
+     */
+    project_id?: PreferenceProjectIdParameter;
+};
+export type ListUserChannelsParams = {
+    /**
+     * Return only channels of this scope; omit for both
+     */
+    channel_scope?: ChannelScope;
+    /**
+     * Return only channels of this kind; omit for all kinds
+     */
+    kind?: ChannelKind;
+};