@appwrite.io/console 17.0.0 → 18.1.0

package/types/services/push.d.ts

@@ -0,0 +1,153 @@
+import { Client } from '../client';
+import { Service } from '../service';
+import type { ResolvedTopic, Topic } from '../topic';
+/** A message delivered on a subscribed topic (the MQTT analog of a Realtime event). */
+export interface PushMessage {
+    topic: string;
+    /** The payload decoded as UTF-8 text, as it was sent. */
+    data: string;
+    /** The raw payload, for binary messages. */
+    payload: Uint8Array;
+    qos: number;
+}
+export type MessageCallback = (message: PushMessage) => void | Promise<void>;
+/** Per-subscription options passed to `subscribe` and `PushSubscription.update`. */
+export interface SubscribeOptions {
+    /**
+     * Also surface each matching message as a browser notification while the tab is
+     * open. Defaults to false.
+     */
+    background?: boolean;
+    /** Notification title for this subscription. Defaults to the message topic. */
+    title?: string;
+    /**
+     * Retry delivery of messages missed while disconnected. `true` (the default) subscribes
+     * at QoS 1 so the broker holds this topic's messages and redelivers them on reconnect;
+     * `false` uses QoS 0 (at-most-once, may be lost). Per-subscription — the connection
+     * always keeps its session (clean start off).
+     */
+    retry?: boolean;
+}
+/**
+ * Handle for a live subscription. `unsubscribe()` drops it (and closes the connection
+ * once the last one is gone); `update()` toggles this subscription's per-message options
+ * without resubscribing.
+ */
+export interface PushSubscription {
+    unsubscribe(): void;
+    update(options: SubscribeOptions): void;
+}
+/**
+ * Appwrite native push service — the Realtime analog over an MQTT broker, without
+ * FCM or APNS. In the browser the transport is MQTT 5 over WebSocket: while the page is
+ * open the connection stays up and each message is handed to your callback, and a
+ * subscription may also opt into a browser notification per message.
+ *
+ * The connection has no tunables — it always keeps its session (clean start off) so the
+ * broker can redeliver missed messages, and reliability is chosen per subscription via
+ * `retry`. `subscribe` opens the connection lazily and returns a
+ * {@link PushSubscription} handle (unlike Realtime's bare unsubscribe callable — Push
+ * carries per-subscription state). The credential is read off the client — set a JWT or
+ * session on it (`Client.setJWT` / `Client.setSession`), the same way every other service
+ * reads auth.
+ *
+ *     const client = new Client().setEndpoint(...).setProject(...).setJWT(jwt);
+ *     const push = new Push(client);
+ *     const sub = await push.subscribe('user/123/#', (m) =>
+ *       console.log(m.topic, m.data),
+ *     );
+ *     // sub.update({ background: true }); sub.unsubscribe();
+ */
+export declare class Push extends Service {
+    private mqtt;
+    private connecting;
+    /** Set once the first CONNACK lands, so 'connect' events after are reconnects. */
+    private everConnected;
+    private onOpenCb?;
+    private onCloseCb?;
+    private onErrorCb?;
+    /** Errors already handed to onError, so one failure is reported once. */
+    private reported;
+    /** mqtt.js connect errors mapped to the error handed out for them (see connectError). */
+    private connectErrors;
+    /** True while the first connect is in flight: its errors go to the waiting caller. */
+    private opening;
+    /**
+     * The client id when the credential names no user (and none was set): random, but kept for
+     * this instance so reconnects resume the same broker session.
+     */
+    private readonly fallbackClientId;
+    private readonly subscriptions;
+    constructor(client: Client);
+    private effectiveQos;
+    /** Register a callback invoked when the connection opens (CONNACK success). */
+    onOpen(callback: () => void): this;
+    /** Register a callback invoked when the connection closes. */
+    onClose(callback: () => void): this;
+    /** Register a callback invoked on a connection error. */
+    onError(callback: (error: Error) => void): this;
+    /**
+     * The signed-in user's own topic, `users/<userId>`, for a topic-less subscribe. The id comes
+     * from the credential the connection authenticates with: the JWT when one is set (never
+     * the session, which could belong to a different user), else the session.
+     */
+    private userTopic;
+    /**
+     * Hand an error to the onError callback, once per error. These errors happen outside any
+     * call (reconnects, broker DISCONNECTs, background re-subscribes), so they are never
+     * thrown, which would crash the app from inside mqtt.js: with no callback registered
+     * they are logged, like Realtime does.
+     */
+    private report;
+    /**
+     * For a call that fails to its caller: report the error to onError when a callback is
+     * registered, then throw it to the caller, who can catch it.
+     */
+    private fail;
+    /**
+     * Subscribe to one or more topics. Resolves to a {@link PushSubscription} handle.
+     *
+     * Each topic is a string or a `Topic` builder, e.g.
+     * `Topic.path(['user', userId]).all()`.
+     *
+     * Called with only a callback, `subscribe((message) => {...}, options)` subscribes to the
+     * signed-in user's own topic, `users/<userId>`, like FCM/APNs delivery to a device. The
+     * user id is read from the JWT (or session) set on the client. This form defaults to
+     * `background: true` and `retry: true` (QoS 1); pass either in the options to override.
+     *
+     * Awaiting resolves only once the broker has acked every SUBSCRIBE (SUBACK):
+     * the broker only starts routing a topic once its subscription is registered,
+     * so publishing before the ack races the message ahead of the subscription and
+     * it is dropped (no retained replay on MQTT). Awaiting here makes
+     * subscribe-then-publish reliable.
+     *
+     * Pass `{ background: true, title }` to also show a browser notification per matching
+     * message while the tab is open, and `{ retry: false }` for at-most-once
+     * (QoS 0) delivery; toggle either later with the handle's `update`.
+     */
+    subscribe(callback: MessageCallback, options?: SubscribeOptions): Promise<PushSubscription>;
+    subscribe(topics: string | Topic | ResolvedTopic | (string | Topic | ResolvedTopic)[], callback: MessageCallback, options?: SubscribeOptions): Promise<PushSubscription>;
+    private subscribeWith;
+    /** Tear down the connection and drop all active subscriptions. */
+    close(): void;
+    /**
+     * Re-register every active subscription. Called on each reconnect so a client that
+     * reconnects with a fresh (or cleared) session does not silently stop receiving;
+     * re-subscribing an existing filter is idempotent.
+     */
+    private resubscribeAll;
+    private connect;
+    private endpointUrl;
+    private open;
+    /**
+     * The error for a failed connect: the broker's Reason String when it sent one (a refused
+     * CONNACK), else mqtt.js's error. Memoized so both error listeners hand out the same
+     * object and it is reported once.
+     */
+    private connectError;
+    /** Fan a delivered packet out to every subscription whose filter matches. */
+    private dispatch;
+    private requestNotificationPermission;
+    /** Post a browser notification for a message a background subscription matched. */
+    private notify;
+}

package/types/services/tables-db.d.ts

@@ -1642,6 +1642,39 @@ export declare class TablesDB {
      * @deprecated Use the object parameter style method for a better developer experience.
      */
     createRelationshipColumn(databaseId: string, tableId: string, relatedTableId: string, type: RelationshipType, twoWay?: boolean, key?: string, twoWayKey?: string, onDelete?: RelationMutate): Promise<Models.ColumnRelationship>;
+    /**
+     * Update relationship column. [Learn more about relationship columns](https://appwrite.io/docs/databases-relationships#relationship-columns).
+     *
+     *
+     * @param {string} params.databaseId - Database ID.
+     * @param {string} params.tableId - Table ID.
+     * @param {string} params.key - Column Key.
+     * @param {RelationMutate} params.onDelete - Delete constraint. Possible values are: cascade, restrict, setNull.
+     * @param {string} params.newKey - New Column Key.
+     * @throws {AppwriteException}
+     * @returns {Promise<Models.ColumnRelationship>}
+     */
+    updateRelationshipColumn(params: {
+        databaseId: string;
+        tableId: string;
+        key: string;
+        onDelete?: RelationMutate;
+        newKey?: string;
+    }): Promise<Models.ColumnRelationship>;
+    /**
+     * Update relationship column. [Learn more about relationship columns](https://appwrite.io/docs/databases-relationships#relationship-columns).
+     *
+     *
+     * @param {string} databaseId - Database ID.
+     * @param {string} tableId - Table ID.
+     * @param {string} key - Column Key.
+     * @param {RelationMutate} onDelete - Delete constraint. Possible values are: cascade, restrict, setNull.
+     * @param {string} newKey - New Column Key.
+     * @throws {AppwriteException}
+     * @returns {Promise<Models.ColumnRelationship>}
+     * @deprecated Use the object parameter style method for a better developer experience.
+     */
+    updateRelationshipColumn(databaseId: string, tableId: string, key: string, onDelete?: RelationMutate, newKey?: string): Promise<Models.ColumnRelationship>;
     /**
      * Create a string column.
      *
@@ -1960,13 +1993,13 @@ export declare class TablesDB {
      * @param {string} params.tableId - Table ID.
      * @param {string} params.key - Column Key.
      * @throws {AppwriteException}
-     * @returns {Promise<Models.ColumnBoolean | Models.ColumnInteger | Models.ColumnFloat | Models.ColumnEmail | Models.ColumnEnum | Models.ColumnUrl | Models.ColumnIp | Models.ColumnDatetime | Models.ColumnRelationship | Models.ColumnString>}
+     * @returns {Promise<Models.ColumnBoolean | Models.ColumnBigint | Models.ColumnInteger | Models.ColumnFloat | Models.ColumnEmail | Models.ColumnEnum | Models.ColumnUrl | Models.ColumnIp | Models.ColumnDatetime | Models.ColumnRelationship | Models.ColumnPoint | Models.ColumnLine | Models.ColumnPolygon | Models.ColumnVarchar | Models.ColumnText | Models.ColumnMediumtext | Models.ColumnLongtext | Models.ColumnString>}
      */
     getColumn(params: {
         databaseId: string;
         tableId: string;
         key: string;
-    }): Promise<Models.ColumnBoolean | Models.ColumnInteger | Models.ColumnFloat | Models.ColumnEmail | Models.ColumnEnum | Models.ColumnUrl | Models.ColumnIp | Models.ColumnDatetime | Models.ColumnRelationship | Models.ColumnString>;
+    }): Promise<Models.ColumnBoolean | Models.ColumnBigint | Models.ColumnInteger | Models.ColumnFloat | Models.ColumnEmail | Models.ColumnEnum | Models.ColumnUrl | Models.ColumnIp | Models.ColumnDatetime | Models.ColumnRelationship | Models.ColumnPoint | Models.ColumnLine | Models.ColumnPolygon | Models.ColumnVarchar | Models.ColumnText | Models.ColumnMediumtext | Models.ColumnLongtext | Models.ColumnString>;
     /**
      * Get column by ID.
      *
@@ -1974,10 +2007,10 @@ export declare class TablesDB {
      * @param {string} tableId - Table ID.
      * @param {string} key - Column Key.
      * @throws {AppwriteException}
-     * @returns {Promise<Models.ColumnBoolean | Models.ColumnInteger | Models.ColumnFloat | Models.ColumnEmail | Models.ColumnEnum | Models.ColumnUrl | Models.ColumnIp | Models.ColumnDatetime | Models.ColumnRelationship | Models.ColumnString>}
+     * @returns {Promise<Models.ColumnBoolean | Models.ColumnBigint | Models.ColumnInteger | Models.ColumnFloat | Models.ColumnEmail | Models.ColumnEnum | Models.ColumnUrl | Models.ColumnIp | Models.ColumnDatetime | Models.ColumnRelationship | Models.ColumnPoint | Models.ColumnLine | Models.ColumnPolygon | Models.ColumnVarchar | Models.ColumnText | Models.ColumnMediumtext | Models.ColumnLongtext | Models.ColumnString>}
      * @deprecated Use the object parameter style method for a better developer experience.
      */
-    getColumn(databaseId: string, tableId: string, key: string): Promise<Models.ColumnBoolean | Models.ColumnInteger | Models.ColumnFloat | Models.ColumnEmail | Models.ColumnEnum | Models.ColumnUrl | Models.ColumnIp | Models.ColumnDatetime | Models.ColumnRelationship | Models.ColumnString>;
+    getColumn(databaseId: string, tableId: string, key: string): Promise<Models.ColumnBoolean | Models.ColumnBigint | Models.ColumnInteger | Models.ColumnFloat | Models.ColumnEmail | Models.ColumnEnum | Models.ColumnUrl | Models.ColumnIp | Models.ColumnDatetime | Models.ColumnRelationship | Models.ColumnPoint | Models.ColumnLine | Models.ColumnPolygon | Models.ColumnVarchar | Models.ColumnText | Models.ColumnMediumtext | Models.ColumnLongtext | Models.ColumnString>;
     /**
      * Deletes a column.
      *
@@ -2003,39 +2036,6 @@ export declare class TablesDB {
      * @deprecated Use the object parameter style method for a better developer experience.
      */
     deleteColumn(databaseId: string, tableId: string, key: string): Promise<{}>;
-    /**
-     * Update relationship column. [Learn more about relationship columns](https://appwrite.io/docs/databases-relationships#relationship-columns).
-     *
-     *
-     * @param {string} params.databaseId - Database ID.
-     * @param {string} params.tableId - Table ID.
-     * @param {string} params.key - Column Key.
-     * @param {RelationMutate} params.onDelete - Delete constraint. Possible values are: cascade, restrict, setNull.
-     * @param {string} params.newKey - New Column Key.
-     * @throws {AppwriteException}
-     * @returns {Promise<Models.ColumnRelationship>}
-     */
-    updateRelationshipColumn(params: {
-        databaseId: string;
-        tableId: string;
-        key: string;
-        onDelete?: RelationMutate;
-        newKey?: string;
-    }): Promise<Models.ColumnRelationship>;
-    /**
-     * Update relationship column. [Learn more about relationship columns](https://appwrite.io/docs/databases-relationships#relationship-columns).
-     *
-     *
-     * @param {string} databaseId - Database ID.
-     * @param {string} tableId - Table ID.
-     * @param {string} key - Column Key.
-     * @param {RelationMutate} onDelete - Delete constraint. Possible values are: cascade, restrict, setNull.
-     * @param {string} newKey - New Column Key.
-     * @throws {AppwriteException}
-     * @returns {Promise<Models.ColumnRelationship>}
-     * @deprecated Use the object parameter style method for a better developer experience.
-     */
-    updateRelationshipColumn(databaseId: string, tableId: string, key: string, onDelete?: RelationMutate, newKey?: string): Promise<Models.ColumnRelationship>;
     /**
      * List indexes on the table.
      *

package/types/services/users.d.ts

@@ -412,7 +412,7 @@ export declare class Users {
      */
     updateEmail<Preferences extends Models.Preferences = Models.DefaultPreferences>(userId: string, email: string): Promise<Models.User<Preferences>>;
     /**
-     * Enable or disable whether a user can impersonate other users. When impersonation headers are used, the request runs as the target user for API behavior, while internal audit logs still attribute the action to the original impersonator and store the impersonated target details only in internal audit payload data.
+     * Enable or disable whether a user can impersonate other users. When impersonation headers are used, the request runs as the target user for API behavior, while internal audit logs still attribute the action to the original impersonator and store the impersonated target details only in internal audit payload data. Account endpoints are read-only while impersonating: they report the target's account, and anything that would change it is refused, so an impersonator cannot alter the target's credentials or delete their account.
      *
      *
      * @param {string} params.userId - User ID.
@@ -425,7 +425,7 @@ export declare class Users {
         impersonator: boolean;
     }): Promise<Models.User<Preferences>>;
     /**
-     * Enable or disable whether a user can impersonate other users. When impersonation headers are used, the request runs as the target user for API behavior, while internal audit logs still attribute the action to the original impersonator and store the impersonated target details only in internal audit payload data.
+     * Enable or disable whether a user can impersonate other users. When impersonation headers are used, the request runs as the target user for API behavior, while internal audit logs still attribute the action to the original impersonator and store the impersonated target details only in internal audit payload data. Account endpoints are read-only while impersonating: they report the target's account, and anything that would change it is refused, so an impersonator cannot alter the target's credentials or delete their account.
      *
      *
      * @param {string} userId - User ID.

package/types/topic.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Helper to build MQTT topics for `Push`, level by level.
+ *
+ *     Topic.path(['user', userId, 'notification']); // "user/123/notification"
+ *     Topic.path(['user']).any().path(['notification']); // "user/+/notification"
+ *     Topic.path(['org']).any().path(['logs']).all(); // "org/+/logs/#"
+ *
+ * `any()` matches exactly one level and `all()` everything below, at any depth (including the
+ * parent itself). `all()` ends the topic, so it returns a {@link ResolvedTopic}.
+ */
+export declare class Topic {
+    private readonly levels;
+    private constructor();
+    /** Start a topic with the given levels, e.g. `Topic.path(['user', userId])`. */
+    static path(levels: string[]): Topic;
+    /** Start a topic with a single-level wildcard (`+`). */
+    static any(): Topic;
+    /** The multi-level wildcard alone (`#`): matches every topic. */
+    static all(): ResolvedTopic;
+    /** Append the given levels. */
+    path(levels: string[]): Topic;
+    /** Append a single-level wildcard (`+`): matches exactly one level. */
+    any(): Topic;
+    /** Append the multi-level wildcard (`#`) and end the topic. */
+    all(): ResolvedTopic;
+    toString(): string;
+}
+/** A topic ended by `all()`: nothing can be appended after the `#` wildcard. */
+export declare class ResolvedTopic {
+    private readonly levels;
+    /** @internal Created by {@link Topic.all}. */
+    constructor(levels: readonly string[]);
+    toString(): string;
+}