@appwrite.io/console 2.1.2 → 2.1.3

package/src/client.ts

@@ -1,6 +1,57 @@
 import { Models } from './models';
+import { Channel, ActionableChannel, ResolvedChannel } from './channel';
 import JSONbigModule from 'json-bigint';
-const JSONbig = JSONbigModule({ useNativeBigInt: true });
+import BigNumber from 'bignumber.js';
+const JSONbigParser = JSONbigModule({ storeAsString: false });
+const JSONbigSerializer = JSONbigModule({ useNativeBigInt: true });
+
+/**
+ * Converts BigNumber objects from json-bigint to native types.
+ * - Integer BigNumbers → BigInt (if unsafe) or number (if safe)
+ * - Float BigNumbers → number
+ * - Strings remain strings (never converted to BigNumber by json-bigint)
+ */
+const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
+const MIN_SAFE = BigInt(Number.MIN_SAFE_INTEGER);
+
+function convertBigNumbers(value: any): any {
+    if (value === null || value === undefined) return value;
+
+    if (Array.isArray(value)) {
+        return value.map(convertBigNumbers);
+    }
+
+    if (BigNumber.isBigNumber(value)) {
+        if (value.isInteger()) {
+            const str = value.toFixed();
+            const bi = BigInt(str);
+
+            if (bi >= MIN_SAFE && bi <= MAX_SAFE) {
+                return Number(str);
+            }
+
+            return bi;
+        }
+
+        // float
+        return value.toNumber();
+    }
+
+    if (typeof value === 'object') {
+        const result: any = {};
+        for (const [k, v] of Object.entries(value)) {
+            result[k] = convertBigNumbers(v);
+        }
+        return result;
+    }
+
+    return value;
+}
+
+const JSONbig = {
+    parse: (text: string) => convertBigNumbers(JSONbigParser.parse(text)),
+    stringify: JSONbigSerializer.stringify
+};
 
 /**
  * Payload type representing a key-value pair with string keys and any values.
@@ -334,7 +385,7 @@ class Client {
         'x-sdk-name': 'Console',
         'x-sdk-platform': 'console',
         'x-sdk-language': 'web',
-        'x-sdk-version': '2.1.2',
+        'x-sdk-version': '2.1.3',
         'X-Appwrite-Response-Format': '1.8.0',
     };
 
@@ -654,8 +705,8 @@ class Client {
      * @deprecated Use the Realtime service instead.
      * @see Realtime
      *
-     * @param {string|string[]} channels
-     * Channel to subscribe - pass a single channel as a string or multiple with an array of strings.
+     * @param {string|string[]|Channel<any>|ActionableChannel|ResolvedChannel|(Channel<any>|ActionableChannel|ResolvedChannel)[]} channels
+     * Channel to subscribe - pass a single channel as a string or Channel builder instance, or multiple with an array.
      *
      * Possible channels are:
      * - account
@@ -673,16 +724,35 @@ class Client {
      * - teams.[ID]
      * - memberships
      * - memberships.[ID]
+     * 
+     * You can also use Channel builders:
+     * - Channel.database('db').collection('col').document('doc').create()
+     * - Channel.bucket('bucket').file('file').update()
+     * - Channel.function('func').execution('exec').delete()
+     * - Channel.team('team').create()
+     * - Channel.membership('membership').update()
      * @param {(payload: RealtimeMessage) => void} callback Is called on every realtime update.
      * @returns {() => void} Unsubscribes from events.
      */
-    subscribe<T extends unknown>(channels: string | string[], callback: (payload: RealtimeResponseEvent<T>) => void): () => void {
-        let channelArray = typeof channels === 'string' ? [channels] : channels;
-        channelArray.forEach(channel => this.realtime.channels.add(channel));
+    subscribe<T extends unknown>(channels: string | string[] | Channel<any> | ActionableChannel | ResolvedChannel | (Channel<any> | ActionableChannel | ResolvedChannel)[], callback: (payload: RealtimeResponseEvent<T>) => void): () => void {
+        const channelArray = Array.isArray(channels) ? channels : [channels];
+        // Convert Channel instances to strings
+        const channelStrings = channelArray.map(ch => {
+            if (typeof ch === 'string') {
+                return ch;
+            }
+            // All Channel instances have toString() method
+            if (ch && typeof (ch as Channel<any>).toString === 'function') {
+                return (ch as Channel<any>).toString();
+            }
+            // Fallback to generic string conversion
+            return String(ch);
+        });
+        channelStrings.forEach(channel => this.realtime.channels.add(channel));
 
         const counter = this.realtime.subscriptionsCounter++;
         this.realtime.subscriptions.set(counter, {
-            channels: channelArray,
+            channels: channelStrings,
             callback
         });
 
@@ -690,7 +760,7 @@ class Client {
 
         return () => {
             this.realtime.subscriptions.delete(counter);
-            this.realtime.cleanUp(channelArray);
+            this.realtime.cleanUp(channelStrings);
             this.realtime.connect();
         }
     }

package/src/index.ts

@@ -36,6 +36,7 @@ export type { QueryTypes, QueryTypesList } from './query';
 export { Permission } from './permission';
 export { Role } from './role';
 export { ID } from './id';
+export { Channel } from './channel';
 export { Operator, Condition } from './operator';
 export { AuthenticatorType } from './enums/authenticator-type';
 export { AuthenticationFactor } from './enums/authentication-factor';

package/src/query.ts

@@ -71,6 +71,16 @@ export class Query {
   static notEqual = (attribute: string, value: QueryTypes): string =>
     new Query("notEqual", attribute, value).toString();
 
+  /**
+   * Filter resources where attribute matches a regular expression pattern.
+   *
+   * @param {string} attribute The attribute to filter on.
+   * @param {string} pattern The regular expression pattern to match.
+   * @returns {string}
+   */
+  static regex = (attribute: string, pattern: string): string =>
+    new Query("regex", attribute, pattern).toString();
+
   /**
    * Filter resources where attribute is less than value.
    *
@@ -129,6 +139,24 @@ export class Query {
   static isNotNull = (attribute: string): string =>
     new Query("isNotNull", attribute).toString();
 
+  /**
+   * Filter resources where the specified attributes exist.
+   *
+   * @param {string[]} attributes The list of attributes that must exist.
+   * @returns {string}
+   */
+  static exists = (attributes: string[]): string =>
+    new Query("exists", undefined, attributes).toString();
+
+  /**
+   * Filter resources where the specified attributes do not exist.
+   *
+   * @param {string[]} attributes The list of attributes that must not exist.
+   * @returns {string}
+   */
+  static notExists = (attributes: string[]): string =>
+    new Query("notExists", undefined, attributes).toString();
+
   /**
    * Filter resources where attribute is between start and end (inclusive).
    *
@@ -378,6 +406,20 @@ export class Query {
   static and = (queries: string[]) =>
     new Query("and", undefined, queries.map((query) => JSONbig.parse(query))).toString();
 
+  /**
+   * Filter array elements where at least one element matches all the specified queries.
+   *
+   * @param {string} attribute The attribute containing the array to filter on.
+   * @param {string[]} queries The list of query strings to match against array elements.
+   * @returns {string}
+   */
+  static elemMatch = (attribute: string, queries: string[]): string =>
+    new Query(
+      "elemMatch",
+      attribute,
+      queries.map((query) => JSONbig.parse(query))
+    ).toString();
+
   /**
    * Filter resources where attribute is at a specific distance from the given coordinates.
    *

package/src/services/realtime.ts

@@ -1,4 +1,5 @@
 import { AppwriteException, Client } from '../client';
+import { Channel, ActionableChannel, ResolvedChannel } from '../channel';
 
 export type RealtimeSubscription = {
     close: () => Promise<void>;
@@ -237,61 +238,83 @@ export class Realtime {
         return new Promise(resolve => setTimeout(resolve, ms));
     }
 
+    /**
+     * Convert a channel value to a string
+     *
+     * @private
+     * @param {string | Channel<any> | ActionableChannel | ResolvedChannel} channel - Channel value (string or Channel builder instance)
+     * @returns {string} Channel string representation
+     */
+    private channelToString(channel: string | Channel<any> | ActionableChannel | ResolvedChannel): string {
+        if (typeof channel === 'string') {
+            return channel;
+        }
+        // All Channel instances have toString() method
+        if (channel && typeof (channel as Channel<any>).toString === 'function') {
+            return (channel as Channel<any>).toString();
+        }
+        return String(channel);
+    }
+
     /**
      * Subscribe to a single channel
      *
-     * @param {string} channel - Channel name to subscribe to
+     * @param {string | Channel<any> | ActionableChannel | ResolvedChannel} channel - Channel name to subscribe to (string or Channel builder instance)
      * @param {Function} callback - Callback function to handle events
      * @returns {Promise<RealtimeSubscription>} Subscription object with close method
      */
     public async subscribe(
-        channel: string,
+        channel: string | Channel<any> | ActionableChannel | ResolvedChannel,
         callback: (event: RealtimeResponseEvent<any>) => void
     ): Promise<RealtimeSubscription>;
 
     /**
      * Subscribe to multiple channels
      *
-     * @param {string[]} channels - Array of channel names to subscribe to
+     * @param {(string | Channel<any> | ActionableChannel | ResolvedChannel)[]} channels - Array of channel names to subscribe to (strings or Channel builder instances)
      * @param {Function} callback - Callback function to handle events
      * @returns {Promise<RealtimeSubscription>} Subscription object with close method
      */
     public async subscribe(
-        channels: string[],
+        channels: (string | Channel<any> | ActionableChannel | ResolvedChannel)[],
         callback: (event: RealtimeResponseEvent<any>) => void
     ): Promise<RealtimeSubscription>;
 
     /**
      * Subscribe to a single channel with typed payload
      *
-     * @param {string} channel - Channel name to subscribe to
+     * @param {string | Channel<any> | ActionableChannel | ResolvedChannel} channel - Channel name to subscribe to (string or Channel builder instance)
      * @param {Function} callback - Callback function to handle events with typed payload
      * @returns {Promise<RealtimeSubscription>} Subscription object with close method
      */
     public async subscribe<T>(
-        channel: string,
+        channel: string | Channel<any> | ActionableChannel | ResolvedChannel,
         callback: (event: RealtimeResponseEvent<T>) => void
     ): Promise<RealtimeSubscription>;
 
     /**
      * Subscribe to multiple channels with typed payload
      *
-     * @param {string[]} channels - Array of channel names to subscribe to
+     * @param {(string | Channel<any> | ActionableChannel | ResolvedChannel)[]} channels - Array of channel names to subscribe to (strings or Channel builder instances)
      * @param {Function} callback - Callback function to handle events with typed payload
      * @returns {Promise<RealtimeSubscription>} Subscription object with close method
      */
     public async subscribe<T>(
-        channels: string[],
+        channels: (string | Channel<any> | ActionableChannel | ResolvedChannel)[],
         callback: (event: RealtimeResponseEvent<T>) => void
     ): Promise<RealtimeSubscription>;
 
     public async subscribe<T = any>(
-        channelsOrChannel: string | string[],
+        channelsOrChannel: string | Channel<any> | ActionableChannel | ResolvedChannel | (string | Channel<any> | ActionableChannel | ResolvedChannel)[],
         callback: (event: RealtimeResponseEvent<T>) => void
     ): Promise<RealtimeSubscription> {
-        const channels = Array.isArray(channelsOrChannel)
-            ? new Set(channelsOrChannel)
-            : new Set([channelsOrChannel]);
+        const channelArray = Array.isArray(channelsOrChannel)
+            ? channelsOrChannel
+            : [channelsOrChannel];
+        
+        // Convert all channels to strings
+        const channelStrings = channelArray.map(ch => this.channelToString(ch));
+        const channels = new Set(channelStrings);
 
         this.subscriptionsCounter++;
         const count = this.subscriptionsCounter;

package/types/channel.d.ts

@@ -0,0 +1,71 @@
+interface Database {
+    _db: any;
+}
+interface Collection {
+    _coll: any;
+}
+interface Document {
+    _doc: any;
+}
+interface TablesDB {
+    _tdb: any;
+}
+interface Table {
+    _tbl: any;
+}
+interface Row {
+    _row: any;
+}
+interface Bucket {
+    _bkt: any;
+}
+interface File {
+    _file: any;
+}
+interface Func {
+    _fn: any;
+}
+interface Execution {
+    _exec: any;
+}
+interface Team {
+    _team: any;
+}
+interface Membership {
+    _mem: any;
+}
+interface Resolved {
+    _res: any;
+}
+declare type Actionable = Document | Row | File | Execution | Team | Membership;
+export declare class Channel<T> {
+    private readonly segments;
+    _type: T;
+    private constructor();
+    private next;
+    private resolve;
+    toString(): string;
+    collection(this: Channel<Database>, id?: string): Channel<Collection>;
+    document(this: Channel<Collection>, id?: string): Channel<Document>;
+    table(this: Channel<TablesDB>, id?: string): Channel<Table>;
+    row(this: Channel<Table>, id?: string): Channel<Row>;
+    file(this: Channel<Bucket>, id?: string): Channel<File>;
+    execution(this: Channel<Func>, id?: string): Channel<Execution>;
+    create(this: Channel<Actionable>): Channel<Resolved>;
+    update(this: Channel<Actionable>): Channel<Resolved>;
+    delete(this: Channel<Actionable>): Channel<Resolved>;
+    static database(id?: string): Channel<Database>;
+    static tablesdb(id?: string): Channel<TablesDB>;
+    static bucket(id?: string): Channel<Bucket>;
+    static function(id?: string): Channel<Func>;
+    static team(id?: string): Channel<Team>;
+    static membership(id?: string): Channel<Membership>;
+    static account(userId?: string): string;
+    static get documents(): string;
+    static get rows(): string;
+    static get files(): string;
+    static get executions(): string;
+}
+export declare type ActionableChannel = Channel<Document> | Channel<Row> | Channel<File> | Channel<Execution> | Channel<Team> | Channel<Membership>;
+export declare type ResolvedChannel = Channel<Resolved>;
+export {};

package/types/client.d.ts

@@ -1,4 +1,5 @@
 import { Models } from './models';
+import { Channel, ActionableChannel, ResolvedChannel } from './channel';
 /**
  * Payload type representing a key-value pair with string keys and any values.
  */
@@ -208,8 +209,8 @@ declare class Client {
      * @deprecated Use the Realtime service instead.
      * @see Realtime
      *
-     * @param {string|string[]} channels
-     * Channel to subscribe - pass a single channel as a string or multiple with an array of strings.
+     * @param {string|string[]|Channel<any>|ActionableChannel|ResolvedChannel|(Channel<any>|ActionableChannel|ResolvedChannel)[]} channels
+     * Channel to subscribe - pass a single channel as a string or Channel builder instance, or multiple with an array.
      *
      * Possible channels are:
      * - account
@@ -227,10 +228,17 @@ declare class Client {
      * - teams.[ID]
      * - memberships
      * - memberships.[ID]
+     *
+     * You can also use Channel builders:
+     * - Channel.database('db').collection('col').document('doc').create()
+     * - Channel.bucket('bucket').file('file').update()
+     * - Channel.function('func').execution('exec').delete()
+     * - Channel.team('team').create()
+     * - Channel.membership('membership').update()
      * @param {(payload: RealtimeMessage) => void} callback Is called on every realtime update.
      * @returns {() => void} Unsubscribes from events.
      */
-    subscribe<T extends unknown>(channels: string | string[], callback: (payload: RealtimeResponseEvent<T>) => void): () => void;
+    subscribe<T extends unknown>(channels: string | string[] | Channel<any> | ActionableChannel | ResolvedChannel | (Channel<any> | ActionableChannel | ResolvedChannel)[], callback: (payload: RealtimeResponseEvent<T>) => void): () => void;
     prepareRequest(method: string, url: URL, headers?: Headers, params?: Payload): {
         uri: string;
         options: RequestInit;

package/types/index.d.ts

@@ -36,6 +36,7 @@ export type { QueryTypes, QueryTypesList } from './query';
 export { Permission } from './permission';
 export { Role } from './role';
 export { ID } from './id';
+export { Channel } from './channel';
 export { Operator, Condition } from './operator';
 export { AuthenticatorType } from './enums/authenticator-type';
 export { AuthenticationFactor } from './enums/authentication-factor';

package/types/query.d.ts

@@ -39,6 +39,14 @@ export declare class Query {
      * @returns {string}
      */
     static notEqual: (attribute: string, value: QueryTypes) => string;
+    /**
+     * Filter resources where attribute matches a regular expression pattern.
+     *
+     * @param {string} attribute The attribute to filter on.
+     * @param {string} pattern The regular expression pattern to match.
+     * @returns {string}
+     */
+    static regex: (attribute: string, pattern: string) => string;
     /**
      * Filter resources where attribute is less than value.
      *
@@ -85,6 +93,20 @@ export declare class Query {
      * @returns {string}
      */
     static isNotNull: (attribute: string) => string;
+    /**
+     * Filter resources where the specified attributes exist.
+     *
+     * @param {string[]} attributes The list of attributes that must exist.
+     * @returns {string}
+     */
+    static exists: (attributes: string[]) => string;
+    /**
+     * Filter resources where the specified attributes do not exist.
+     *
+     * @param {string[]} attributes The list of attributes that must not exist.
+     * @returns {string}
+     */
+    static notExists: (attributes: string[]) => string;
     /**
      * Filter resources where attribute is between start and end (inclusive).
      *
@@ -282,6 +304,14 @@ export declare class Query {
      * @returns {string}
      */
     static and: (queries: string[]) => string;
+    /**
+     * Filter array elements where at least one element matches all the specified queries.
+     *
+     * @param {string} attribute The attribute containing the array to filter on.
+     * @param {string[]} queries The list of query strings to match against array elements.
+     * @returns {string}
+     */
+    static elemMatch: (attribute: string, queries: string[]) => string;
     /**
      * Filter resources where attribute is at a specific distance from the given coordinates.
      *

package/types/services/realtime.d.ts

@@ -1,4 +1,5 @@
 import { Client } from '../client';
+import { Channel, ActionableChannel, ResolvedChannel } from '../channel';
 export declare type RealtimeSubscription = {
     close: () => Promise<void>;
 };
@@ -78,38 +79,46 @@ export declare class Realtime {
     private closeSocket;
     private getTimeout;
     private sleep;
+    /**
+     * Convert a channel value to a string
+     *
+     * @private
+     * @param {string | Channel<any> | ActionableChannel | ResolvedChannel} channel - Channel value (string or Channel builder instance)
+     * @returns {string} Channel string representation
+     */
+    private channelToString;
     /**
      * Subscribe to a single channel
      *
-     * @param {string} channel - Channel name to subscribe to
+     * @param {string | Channel<any> | ActionableChannel | ResolvedChannel} channel - Channel name to subscribe to (string or Channel builder instance)
      * @param {Function} callback - Callback function to handle events
      * @returns {Promise<RealtimeSubscription>} Subscription object with close method
      */
-    subscribe(channel: string, callback: (event: RealtimeResponseEvent<any>) => void): Promise<RealtimeSubscription>;
+    subscribe(channel: string | Channel<any> | ActionableChannel | ResolvedChannel, callback: (event: RealtimeResponseEvent<any>) => void): Promise<RealtimeSubscription>;
     /**
      * Subscribe to multiple channels
      *
-     * @param {string[]} channels - Array of channel names to subscribe to
+     * @param {(string | Channel<any> | ActionableChannel | ResolvedChannel)[]} channels - Array of channel names to subscribe to (strings or Channel builder instances)
      * @param {Function} callback - Callback function to handle events
      * @returns {Promise<RealtimeSubscription>} Subscription object with close method
      */
-    subscribe(channels: string[], callback: (event: RealtimeResponseEvent<any>) => void): Promise<RealtimeSubscription>;
+    subscribe(channels: (string | Channel<any> | ActionableChannel | ResolvedChannel)[], callback: (event: RealtimeResponseEvent<any>) => void): Promise<RealtimeSubscription>;
     /**
      * Subscribe to a single channel with typed payload
      *
-     * @param {string} channel - Channel name to subscribe to
+     * @param {string | Channel<any> | ActionableChannel | ResolvedChannel} channel - Channel name to subscribe to (string or Channel builder instance)
      * @param {Function} callback - Callback function to handle events with typed payload
      * @returns {Promise<RealtimeSubscription>} Subscription object with close method
      */
-    subscribe<T>(channel: string, callback: (event: RealtimeResponseEvent<T>) => void): Promise<RealtimeSubscription>;
+    subscribe<T>(channel: string | Channel<any> | ActionableChannel | ResolvedChannel, callback: (event: RealtimeResponseEvent<T>) => void): Promise<RealtimeSubscription>;
     /**
      * Subscribe to multiple channels with typed payload
      *
-     * @param {string[]} channels - Array of channel names to subscribe to
+     * @param {(string | Channel<any> | ActionableChannel | ResolvedChannel)[]} channels - Array of channel names to subscribe to (strings or Channel builder instances)
      * @param {Function} callback - Callback function to handle events with typed payload
      * @returns {Promise<RealtimeSubscription>} Subscription object with close method
      */
-    subscribe<T>(channels: string[], callback: (event: RealtimeResponseEvent<T>) => void): Promise<RealtimeSubscription>;
+    subscribe<T>(channels: (string | Channel<any> | ActionableChannel | ResolvedChannel)[], callback: (event: RealtimeResponseEvent<T>) => void): Promise<RealtimeSubscription>;
     private cleanUp;
     private handleMessage;
     private handleResponseConnected;