@leaflow/sdk 0.178.0 → 0.180.0

package/dist/eventbus/v1/generated/functions.js

@@ -1,3 +1,133 @@
+export const getListNamespacesUrl = (params) => {
+    const normalizedParams = new URLSearchParams();
+    Object.entries(params || {}).forEach(([key, value]) => {
+        if (value !== undefined) {
+            normalizedParams.append(key, value === null ? "null" : String(value));
+        }
+    });
+    const stringifiedParams = normalizedParams.toString();
+    return stringifiedParams.length > 0
+        ? `https://eventbus.leaflow.cloud/api/v1/namespaces?${stringifiedParams}`
+        : `https://eventbus.leaflow.cloud/api/v1/namespaces`;
+};
+/**
+ * Returns the platform namespaces followed by the project's own, each group ordered by name.
+ * Archived namespaces are omitted unless `include_archived` is true.
+ * @summary List namespaces
+ */
+export const listNamespaces = async (params, options, fetchFn) => {
+    const res = await (fetchFn ?? fetch)(getListNamespacesUrl(params), {
+        ...options,
+        method: "GET",
+    });
+    const body = [204, 205, 304].includes(res.status) ? null : await res.text();
+    const data = body ? JSON.parse(body) : {};
+    return { data, status: res.status, headers: res.headers };
+};
+export const getCreateNamespaceUrl = () => {
+    return `https://eventbus.leaflow.cloud/api/v1/namespaces`;
+};
+/**
+ * Creates a namespace in the current project. Its name is a single segment, unique within the
+ * project; names reserved for the platform are rejected.
+ * @summary Create a namespace
+ */
+export const createNamespace = async (createNamespaceRequest, options, fetchFn) => {
+    const getHeaders = (h) => {
+        if (!h)
+            return {};
+        if (h instanceof Headers)
+            return Object.fromEntries(h.entries());
+        if (Symbol.iterator in h) {
+            return Object.fromEntries(Array.from(h, (entry) => Array.from(entry)));
+        }
+        const headers = {};
+        for (const [name, value] of Object.entries(h)) {
+            if (value !== undefined)
+                headers[name] = value;
+        }
+        return headers;
+    };
+    const res = await (fetchFn ?? fetch)(getCreateNamespaceUrl(), {
+        ...options,
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...getHeaders(options?.headers) },
+        body: JSON.stringify(createNamespaceRequest),
+    });
+    const body = [204, 205, 304].includes(res.status) ? null : await res.text();
+    const data = body ? JSON.parse(body) : {};
+    return { data, status: res.status, headers: res.headers };
+};
+export const getGetNamespaceUrl = (namespaceName) => {
+    return `https://eventbus.leaflow.cloud/api/v1/namespaces/${encodeURIComponent(String(namespaceName))}`;
+};
+/**
+ * Returns a platform namespace or one of the project's own.
+ * @summary Get a namespace
+ */
+export const getNamespace = async (namespaceName, options, fetchFn) => {
+    const res = await (fetchFn ?? fetch)(getGetNamespaceUrl(namespaceName), {
+        ...options,
+        method: "GET",
+    });
+    const body = [204, 205, 304].includes(res.status) ? null : await res.text();
+    const data = body ? JSON.parse(body) : {};
+    return { data, status: res.status, headers: res.headers };
+};
+export const getUpdateNamespaceUrl = (namespaceName) => {
+    return `https://eventbus.leaflow.cloud/api/v1/namespaces/${encodeURIComponent(String(namespaceName))}`;
+};
+/**
+ * Changes the description or status of one of the project's namespaces. Only the fields
+ * present in the request are changed. While a namespace is archived, its events cannot be
+ * created, published or subscribed to; restoring it lifts that. Platform namespaces cannot be
+ * changed.
+ * @summary Update a namespace
+ */
+export const updateNamespace = async (namespaceName, updateNamespaceRequest, options, fetchFn) => {
+    const getHeaders = (h) => {
+        if (!h)
+            return {};
+        if (h instanceof Headers)
+            return Object.fromEntries(h.entries());
+        if (Symbol.iterator in h) {
+            return Object.fromEntries(Array.from(h, (entry) => Array.from(entry)));
+        }
+        const headers = {};
+        for (const [name, value] of Object.entries(h)) {
+            if (value !== undefined)
+                headers[name] = value;
+        }
+        return headers;
+    };
+    const res = await (fetchFn ?? fetch)(getUpdateNamespaceUrl(namespaceName), {
+        ...options,
+        method: "PATCH",
+        headers: { "Content-Type": "application/json", ...getHeaders(options?.headers) },
+        body: JSON.stringify(updateNamespaceRequest),
+    });
+    const body = [204, 205, 304].includes(res.status) ? null : await res.text();
+    const data = body ? JSON.parse(body) : {};
+    return { data, status: res.status, headers: res.headers };
+};
+export const getDeleteNamespaceUrl = (namespaceName) => {
+    return `https://eventbus.leaflow.cloud/api/v1/namespaces/${encodeURIComponent(String(namespaceName))}`;
+};
+/**
+ * Deletes one of the project's namespaces together with every event and version in it.
+ * Publishing or subscribing to those events fails from then on. Platform namespaces cannot be
+ * deleted.
+ * @summary Delete a namespace
+ */
+export const deleteNamespace = async (namespaceName, options, fetchFn) => {
+    const res = await (fetchFn ?? fetch)(getDeleteNamespaceUrl(namespaceName), {
+        ...options,
+        method: "DELETE",
+    });
+    const body = [204, 205, 304].includes(res.status) ? null : await res.text();
+    const data = body ? JSON.parse(body) : undefined;
+    return { data, status: res.status, headers: res.headers };
+};
 export const getListEventsUrl = (params) => {
     const normalizedParams = new URLSearchParams();
     Object.entries(params || {}).forEach(([key, value]) => {
@@ -11,8 +141,7 @@ export const getListEventsUrl = (params) => {
         : `https://eventbus.leaflow.cloud/api/v1/events`;
 };
 /**
- * Returns the global events visible to the project and the project's own events. Ordered by
- * name.
+ * Returns the platform events and the project's own events. Ordered by name.
  * @summary List event definitions
  */
 export const listEvents = async (params, options, fetchFn) => {
@@ -28,8 +157,8 @@ export const getCreateEventUrl = () => {
     return `https://eventbus.leaflow.cloud/api/v1/events`;
 };
 /**
- * Creates a project event with its first version. The name is unique within the project. The
- * first segment of the name is the event's namespace and must not be a platform namespace.
+ * Creates an event with its first version in one of the project's namespaces. The first
+ * segment of the name is that namespace, followed by at least a resource and an action.
  * @summary Create an event definition
  */
 export const createEvent = async (createEventRequest, options, fetchFn) => {
@@ -159,16 +288,17 @@ export const getEventVersion = async (eventName, version, options, fetchFn) => {
     const data = body ? JSON.parse(body) : {};
     return { data, status: res.status, headers: res.headers };
 };
-export const getPublishEventUrl = (eventName) => {
-    return `https://eventbus.leaflow.cloud/api/v1/events/${encodeURIComponent(String(eventName))}:publish`;
+export const getPublishEventsUrl = () => {
+    return `https://eventbus.leaflow.cloud/api/v1/events:publish`;
 };
 /**
- * Validates the payload against the selected version and publishes the message. The response
- * carries the message identity; it does not mean a consumer received it. A version of zero
- * selects the highest active version.
- * @summary Publish an event message
+ * Validates every message against its selected version and publishes the batch. If any message
+ * is rejected, none is published. The response carries the identity of each message in request
+ * order; it does not mean a consumer received it. Only events defined by the current project can
+ * be published here.
+ * @summary Publish event messages
  */
-export const publishEvent = async (eventName, publishRequest, options, fetchFn) => {
+export const publishEvents = async (publishRequest, options, fetchFn) => {
     const getHeaders = (h) => {
         if (!h)
             return {};
@@ -184,7 +314,7 @@ export const publishEvent = async (eventName, publishRequest, options, fetchFn)
         }
         return headers;
     };
-    const res = await (fetchFn ?? fetch)(getPublishEventUrl(eventName), {
+    const res = await (fetchFn ?? fetch)(getPublishEventsUrl(), {
         ...options,
         method: "POST",
         headers: { "Content-Type": "application/json", ...getHeaders(options?.headers) },
@@ -198,15 +328,72 @@ export const getCreateRealtimeTicketUrl = () => {
     return `https://eventbus.leaflow.cloud/api/v1/realtime/tickets`;
 };
 /**
- * Issues a short-lived ticket for a realtime connection. Connect to `url`, pass the ticket,
- * then authenticate the connection with a scoped token. A ticket is not a bearer token for
- * other APIs.
+ * Issues a short-lived ticket for the named events in the current project. For an event defined
+ * by the project, the ticket covers messages sent to the members of the project and messages
+ * sent to the caller within it. For a platform event, it also covers messages sent to the caller
+ * outside any project and messages sent to no recipient; messages sent within the project are
+ * covered as far as the caller's current permissions allow, which may be limited to some
+ * resources or to none. The caller must still be a member of the project. The ticket lives no
+ * longer than the scoped token it was created with. It is not a bearer token for other APIs.
  * @summary Create a realtime ticket
  */
-export const createRealtimeTicket = async (options, fetchFn) => {
+export const createRealtimeTicket = async (realtimeTicketRequest, options, fetchFn) => {
+    const getHeaders = (h) => {
+        if (!h)
+            return {};
+        if (h instanceof Headers)
+            return Object.fromEntries(h.entries());
+        if (Symbol.iterator in h) {
+            return Object.fromEntries(Array.from(h, (entry) => Array.from(entry)));
+        }
+        const headers = {};
+        for (const [name, value] of Object.entries(h)) {
+            if (value !== undefined)
+                headers[name] = value;
+        }
+        return headers;
+    };
     const res = await (fetchFn ?? fetch)(getCreateRealtimeTicketUrl(), {
         ...options,
         method: "POST",
+        headers: { "Content-Type": "application/json", ...getHeaders(options?.headers) },
+        body: JSON.stringify(realtimeTicketRequest),
+    });
+    const body = [204, 205, 304].includes(res.status) ? null : await res.text();
+    const data = body ? JSON.parse(body) : {};
+    return { data, status: res.status, headers: res.headers };
+};
+export const getCreateAccountRealtimeTicketUrl = () => {
+    return `https://eventbus.leaflow.cloud/api/v1/account/realtime/tickets`;
+};
+/**
+ * Issues a short-lived ticket for a caller who has not selected a project, or belongs to none. Only
+ * platform events are accepted, and the ticket covers only messages sent to the caller outside
+ * any project or to no recipient. The ticket cannot publish. Its `client_id_prefix` is `user.{user_id}.`. The
+ * ticket lives no longer than the token it was created with.
+ * @summary Create an account realtime ticket
+ */
+export const createAccountRealtimeTicket = async (realtimeTicketRequest, options, fetchFn) => {
+    const getHeaders = (h) => {
+        if (!h)
+            return {};
+        if (h instanceof Headers)
+            return Object.fromEntries(h.entries());
+        if (Symbol.iterator in h) {
+            return Object.fromEntries(Array.from(h, (entry) => Array.from(entry)));
+        }
+        const headers = {};
+        for (const [name, value] of Object.entries(h)) {
+            if (value !== undefined)
+                headers[name] = value;
+        }
+        return headers;
+    };
+    const res = await (fetchFn ?? fetch)(getCreateAccountRealtimeTicketUrl(), {
+        ...options,
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...getHeaders(options?.headers) },
+        body: JSON.stringify(realtimeTicketRequest),
     });
     const body = [204, 205, 304].includes(res.status) ? null : await res.text();
     const data = body ? JSON.parse(body) : {};

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

@@ -4,20 +4,18 @@
  * Leaflow Event Bus API
  * Event definitions, versions, publishing, and realtime access.
  *
- * ## 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.
- *
  * ## Definitions and messages
  *
  * An event is a definition: a name, a description, and one or more versions. A version carries a
  * JSON Schema that every published payload must satisfy. Messages are not stored here and are
  * not part of the event definition.
  *
- * A project event belongs to the current project. A global event has no `project_id`; it is
- * defined by a platform service and is read-only in this API. Global events are listed alongside
- * the project's own events.
+ * Every event belongs to a namespace, and its name is the namespace's name, a dot, and at least a
+ * resource and an action, such as `acme.order.created`. A project creates its own namespaces and
+ * defines events in them. Platform namespaces, such as `leaflow.notification`, are maintained by
+ * platform services: their events are listed alongside the project's own and can be subscribed
+ * to, but cannot be changed or published here, and the namespaces cannot be changed or deleted.
+ * Events in a platform namespace are called platform events below.
  *
  * A version number never changes meaning. Adding optional properties is allowed within a version;
  * a breaking change creates a new version. Publishing without a version uses the highest active
@@ -25,15 +23,62 @@
  *
  * ## Publishing
  *
- * Publishing returns the identity of the message and does not wait for consumers. Messages are
- * not stored and are not replayed: a consumer that connects later does not receive earlier
- * messages. Consumers receive messages through the realtime API or the platform's service API.
+ * Messages are published in batches of up to 64. A batch is validated as a whole: if any message
+ * is rejected, none is published. Publishing returns the identity of each message and does not
+ * wait for consumers. Messages are not stored and are not replayed: a consumer that connects
+ * later does not receive earlier messages.
+ *
+ * Messages published through this API are sent to the current project. A message may name one
+ * `subject`, a member of the project; it is then sent to that member only. Without a subject it is
+ * sent to every member of the project.
+ *
+ * Every publication names a `client_id`. It starts with the prefix returned with a realtime
+ * ticket, `user.{user_id}.project.{project_id}.`, followed by one segment chosen by the
+ * client, such as a random identifier per browser tab. Receivers get it unchanged, so a client
+ * can recognise its own messages. A client ID does not need to be unique: several connections
+ * may share one.
  *
  * ## Realtime
  *
- * Create a ticket, connect to the returned URL with the ticket, and authenticate the connection
- * with a scoped token. A ticket is single-use and short-lived. The connection ends when the
- * token expires unless it is refreshed with a new scoped token for the same user and project.
+ * Every message has a topic `{event}/{project_id|-}/{subject|-}/{key levels}`, where `-` stands
+ * for a missing recipient and the key, split at `/`, supplies the remaining levels. A topic filter
+ * uses `+` to match exactly one level and `#`, only as the last level, to match that level and
+ * every level below it, including none. For example, `{event}/{project_id}/-/#` matches every
+ * message sent to the members of a project, and `{event}/-/{user_id}/#` every message sent to one
+ * person outside any project.
+ *
+ * 1. Create a ticket with `POST /api/v1/realtime/tickets`, naming the events to receive. The
+ *    response lists the topic filters the ticket covers and the `client_id_prefix` to use. For a
+ *    platform event they cover messages sent to the caller, messages sent to no recipient and,
+ *    where the caller's permissions allow, messages sent within the project; for a project event
+ *    they cover messages sent within the project. Without a selected project, use
+ *    `POST /api/v1/account/realtime/tickets`; such a ticket covers only messages sent to the
+ *    caller or to no recipient, and cannot publish.
+ * 2. Open a WebSocket to `wss://eventbus.leaflow.cloud/realtime` and send, within 15 seconds:
+ *    `{"type":"authenticate","ticket":"…","client_id":"…"}`. The reply is
+ *    `{"type":"authenticated","client_id":"…","connection_id":"…","expires_at":"…"}`.
+ *    `connection_id` identifies this connection; it is assigned by EventBus and changes on
+ *    every reconnection.
+ * 3. Send `{"type":"subscribe","id":"…","topics":[…]}`. Each topic must be one of the returned
+ *    `topics` or lie within one of them, for example by naming a key level where the ticket has
+ *    `#`; a batch with any other topic is rejected as a whole. The reply is `subscribed`.
+ *    `unsubscribe` takes the same form and replies `unsubscribed`. Both may be sent at any time
+ *    while the connection is open.
+ * 4. Messages arrive as `{"type":"messages","messages":[…]}`, each element an `EventMessage`. A
+ *    message matching several subscriptions on one connection arrives once for each of them.
+ * 5. A connection may switch to another ticket of the same user at any time by sending
+ *    `authenticate` again: to renew before `expires_at`, to move from an account ticket to a
+ *    project ticket, or to move to another project. `client_id` may be omitted while the
+ *    `client_id_prefix` stays the same; when it changes, a client ID under the new prefix is
+ *    required. Subscriptions the new ticket does not cover are removed at once and reported in a
+ *    `{"type":"revoked","topics":[…]}` frame. A ticket for another user closes the connection
+ *    with code 4401, as does letting the ticket expire.
+ *
+ * A connection holding a project ticket may publish the project's own events with
+ * `{"type":"publish","id":"…","messages":[{"event":"…","key":"…","subject":"…","data":{…}}]}`;
+ * the reply is `published` with the identity of each message. `ping` is answered with `pong`.
+ * A rejected request is answered with `{"type":"error","id":"…","code":"…","message":"…"}`.
+ * Every reply carries the `id` of the request it answers.
  * OpenAPI spec version: 1.0.0
  */
 export interface FieldViolation {
@@ -104,6 +149,56 @@ export declare const EventStatus: {
     readonly active: "active";
     readonly archived: "archived";
 };
+/**
+ * `active` admits its events. `archived` keeps them readable but rejects new events, messages
+ * and subscriptions.
+ */
+export type NamespaceStatus = (typeof NamespaceStatus)[keyof typeof NamespaceStatus];
+export declare const NamespaceStatus: {
+    readonly active: "active";
+    readonly archived: "archived";
+};
+export interface NamespaceResource {
+    /**
+     * The namespace's name; every event in it is named with this prefix and a dot
+     * @maxLength 64
+     */
+    name: string;
+    /** The owning project; absent for a platform namespace, which is maintained by a platform service and is read-only */
+    project_id?: string;
+    /** @maxLength 1024 */
+    description: string;
+    status: NamespaceStatus;
+    created_at: string;
+    updated_at: string;
+}
+export interface NamespaceList {
+    items: NamespaceResource[];
+    /**
+     * The number of namespaces matching the filters
+     * @minimum 0
+     */
+    total_count: number;
+    /** @minimum 1 */
+    page: number;
+    /** @minimum 1 */
+    page_size: number;
+}
+export interface CreateNamespaceRequest {
+    /**
+     * A single segment of lowercase letters, digits and underscores, starting with a letter
+     * @maxLength 64
+     * @pattern ^[a-z](?:[a-z0-9_]*[a-z0-9])?$
+     */
+    name: string;
+    /** @maxLength 1024 */
+    description?: string;
+}
+export interface UpdateNamespaceRequest {
+    /** @maxLength 1024 */
+    description?: string;
+    status?: NamespaceStatus;
+}
 export interface EventResource {
     /**
      * The full event name
@@ -111,7 +206,12 @@ export interface EventResource {
      */
     name: string;
     /**
-     * The owning project; absent for a global event
+     * The namespace the event belongs to; the name starts with it and a dot
+     * @maxLength 64
+     */
+    namespace: string;
+    /**
+     * The owning project; absent for an event in a platform namespace
      * @nullable
      */
     project_id?: string | null;
@@ -175,7 +275,12 @@ export interface EventDetail {
      */
     name: string;
     /**
-     * The owning project; absent for a global event
+     * The namespace the event belongs to; the name starts with it and a dot
+     * @maxLength 64
+     */
+    namespace: string;
+    /**
+     * The owning project; absent for an event in a platform namespace
      * @nullable
      */
     project_id?: string | null;
@@ -275,25 +380,48 @@ export interface UpdateEventRequest {
 /**
  * The message payload
  */
-export type PublishRequestData = {
+export type PublicationData = {
     [key: string]: unknown;
 };
-export interface PublishRequest {
+export interface Publication {
+    /**
+     * The name of an event defined by the current project
+     * @maxLength 128
+     */
+    event: string;
     /**
      * The version to validate against; zero selects the highest active version
      * @minimum 0
      */
     version?: number;
     /**
-     * The ordering key. Messages with the same key reach an individual consumer in publication
-     * order. Defaults to the project id when absent.
+     * The last levels of the message's topic, separated by `/`. Subscribers select messages by
+     * level. No level may be empty, and neither `+` nor `#` may appear.
      * @maxLength 256
      */
     key?: string;
+    /**
+     * A member of the current project; when set, only that member receives the message
+     * @maxLength 128
+     */
+    subject?: string;
     /** The message payload */
-    data: PublishRequestData;
+    data: PublicationData;
 }
-export interface PublishResponse {
+export interface PublishRequest {
+    /**
+     * The publishing client: the caller's prefix, `user.{user_id}.project.{project_id}.`,
+     * followed by one segment of up to 64 letters, digits, hyphens or underscores
+     * @maxLength 192
+     */
+    client_id: string;
+    /**
+     * @minItems 1
+     * @maxItems 64
+     */
+    messages: Publication[];
+}
+export interface PublishedMessage {
     /** The message identity; consumers use it to discard duplicates */
     id: string;
     /** The event name */
@@ -306,13 +434,53 @@ export interface PublishResponse {
     /** When the message was accepted, in UTC RFC 3339 */
     created_at: string;
 }
+export interface PublishResponse {
+    /** One entry per published message, in request order */
+    messages: PublishedMessage[];
+}
+export interface RealtimeTicketRequest {
+    /**
+     * The events to receive, each named once
+     * @minItems 1
+     * @maxItems 64
+     * @items.maxLength 128
+     */
+    events: string[];
+}
 export interface RealtimeTicket {
-    /** The WebSocket URL to connect to */
-    url: string;
-    /** The ticket to present when connecting */
+    /** The ticket to present in the first frame of a realtime connection */
     ticket: string;
-    /** When the ticket expires, in UTC RFC 3339 */
+    /** When the ticket expires, in UTC RFC 3339; renew the connection before then */
     expires_at: string;
+    /** The prefix every client ID on this ticket must start with */
+    client_id_prefix: string;
+    /** The topic filters the ticket covers; subscribe to these or to filters within them */
+    topics: string[];
+}
+export type EventMessageData = {
+    [key: string]: unknown;
+};
+/**
+ * A message as delivered over a realtime connection
+ */
+export interface EventMessage {
+    id: string;
+    event: string;
+    /** @minimum 1 */
+    version: number;
+    key?: string;
+    /** The publisher; the platform service for an event in a platform namespace, or the publishing user otherwise */
+    source: string;
+    /** The publishing client, exactly as it identified itself */
+    client_id: string;
+    /** The realtime connection the message was published on; absent for messages published over HTTP or by platform services */
+    connection_id?: string;
+    /** The project the message was sent to */
+    project_id?: string;
+    /** The person the message was sent to */
+    subject?: string;
+    created_at: string;
+    data: EventMessageData;
 }
 /**
  * Pagination metadata for stable numbered pages. total_count is returned only when the operation can determine it without an unbounded scan.
@@ -334,6 +502,29 @@ export interface CursorPagination {
     /** @nullable */
     next_cursor?: string | null;
 }
+export type ListNamespacesParams = {
+    /**
+     * 1-based page number. Defaults to 1.
+     * @minimum 1
+     * @maximum 2147483647
+     */
+    page?: number;
+    /**
+     * Items per page. Defaults to 50; at most 200.
+     * @minimum 1
+     * @maximum 200
+     */
+    page_size?: number;
+    /**
+     * Match the namespace name or description, case-insensitively
+     * @maxLength 128
+     */
+    keyword?: string;
+    /**
+     * Include archived namespaces; defaults to false
+     */
+    include_archived?: boolean;
+};
 export type ListEventsParams = {
     /**
      * 1-based page number. Defaults to 1.

package/dist/eventbus/v1/generated/models.js

@@ -2,6 +2,10 @@ export const EventStatus = {
     active: "active",
     archived: "archived",
 };
+export const NamespaceStatus = {
+    active: "active",
+    archived: "archived",
+};
 export const EventVersionStatus = {
     active: "active",
     archived: "archived",