skapi-js 1.6.0 → 1.6.2

package/dist/skapi.d.mts

@@ -43,14 +43,14 @@ type WebSocketMessage = {
 };
 type RealtimeCallback = (rt: WebSocketMessage) => void;
 type DelRecordQuery = GetRecordQuery & {
-    unique_id?: string | string[];
-    record_id?: string | string[];
+    unique_id?: string;
+    record_id?: string;
 };
 type GetRecordQuery = {
     unique_id?: string;
     record_id?: string;
-    /** Table name not required when "record_id" is given.*/
-    table?: {
+    /** Table name not required when "record_id" is given. A bare string is shorthand for { name: <string> }. */
+    table?: string | {
         /** Max 128 chars. Blocks: / ! * #, control chars, and sentinel 􏿿. */
         name: string;
         /** Number range: 0 ~ 99. Default: 'public' */
@@ -58,7 +58,11 @@ type GetRecordQuery = {
         /** User ID of subscription */
         subscription?: string;
     };
-    reference?: string;
+    reference?: string | {
+        record_id?: string;
+        unique_id?: string;
+        user_id?: string;
+    };
     /** Index condition and range cannot be used simultaneously.*/
     index?: {
         /** Custom names: max 128 chars, cannot start with "$", blocks / ! * #, control chars, and sentinel 􏿿. Reserved names: $uploaded, $updated, $referenced_count, $user_id. */
@@ -509,6 +513,12 @@ type ConnectionInfo = {
     service_description: string;
     version: string;
     ai_agent: string;
+    conf: {
+        freeze_database: boolean;
+        prevent_signup: boolean;
+        prevent_inquiry: boolean;
+        prevent_anonymous: boolean;
+    };
 };
 type Table = {
     table: string;
@@ -720,11 +730,11 @@ declare class Skapi {
     constructor(service: string, owner?: string | Options, options?: Options | any, __etc?: any);
     /**
      * Returns current connection metadata such as service name, client IP, user agent, locale, and SDK version.
-     * @param params Request parameters.
+     * @param params Request parameters. When `refresh` is true, the cached connection metadata is re-fetched before returning; otherwise the cached connection is returned.
      * @returns A promise that resolves to Promise<ConnectionInfo>.
      */
     getConnectionInfo(params?: {
-        refresh: Boolean;
+        refresh?: boolean;
     }): Promise<ConnectionInfo>;
     private _updateConnection;
     private registerTicket;
@@ -762,12 +772,13 @@ declare class Skapi {
     connectRTC(params: RTCConnectorParams, callback: (e: RTCEvent) => void): Promise<RTCConnector>;
     /**
      * Opens a realtime WebSocket connection and registers a callback for incoming realtime messages.
+     * The WebSocket is delivered through the callback (and stored on the instance); on the initial connection the returned promise resolves to undefined rather than the socket.
      * @param callback Callback invoked for events or updates.
-     * @returns A promise that resolves to Promise<WebSocket>.
+     * @returns A promise that resolves to Promise<WebSocket | void>.
      */
-    connectRealtime(callback: RealtimeCallback): Promise<WebSocket>;
+    connectRealtime(callback: RealtimeCallback): Promise<WebSocket | void>;
     /**
-     * Runs a spellcast operation and stores or returns generated spell data.
+     * Casts a spell (uploads the given spell/name). The server response is not surfaced; resolves to a fixed confirmation string.
      * @param params Request parameters.
      * @returns A promise that resolves to Promise<string>.
      */
@@ -790,25 +801,25 @@ declare class Skapi {
         magic?: any;
     }>>;
     /**
-     * Sends a dopamine message payload and returns the previous message.
+     * Uploads a dopamine message. In non-browser runtimes, resolves to a formatted string (including the video URL, and the previous message if one exists); in the browser it alerts and redirects, resolving to undefined.
      * @param params Request parameters.
-     * @returns A promise that resolves to Promise<string>.
+     * @returns A promise that resolves to Promise<string | void>.
      */
     dopamine(params: {
         message: string;
         name: string;
-    }): Promise<string>;
+    }): Promise<string | void>;
     /**
      * Queries unique ID records by unique_id or condition filters.
      * @param params Request parameters.
      * @param fetchOptions Pagination and fetch behavior options.
      * @returns A promise that resolves to Promise<DatabaseResponse<UniqueId>>.
      */
-    getUniqueId(params: Form<{
+    getUniqueId(params?: Form<{
         /** Unique ID */
         unique_id?: string;
-        /** String query condition for tag name. */
-        condition?: Condition;
+        /** String query condition for the unique_id value. */
+        condition?: Condition | 'ne' | '!=';
     }>, fetchOptions?: FetchOptions): Promise<DatabaseResponse<UniqueId>>;
     /**
      * Resends an existing user invitation email to the target address.
@@ -817,7 +828,6 @@ declare class Skapi {
      */
     resendInvitation(params: Form<{
         email: string;
-        confirmation_url?: string;
     }>): Promise<'SUCCESS: Invitation has been re-sent. (User ID: xxx...)'>;
     /**
      * Cancels a pending invitation for the target email address.
@@ -833,9 +843,9 @@ declare class Skapi {
      * @param fetchOptions Pagination and fetch behavior options.
      * @returns A promise that resolves to Promise<DatabaseResponse<UserProfile>>.
      */
-    getInvitations(params: Form<{
+    getInvitations(params?: Form<{
         email?: string;
-    }>, fetchOptions: FetchOptions): Promise<DatabaseResponse<UserProfile>>;
+    }>, fetchOptions?: FetchOptions): Promise<DatabaseResponse<UserProfile>>;
     /**
      * Completes OpenID login and optionally merges the OpenID identity with an existing account.
      * @param params Request parameters.
@@ -895,7 +905,7 @@ declare class Skapi {
         in_queue: number;
         poll?: (arg?: {
             latency?: number;
-        }) => void;
+        }) => Promise<any>;
     }>;
     /**
      * Retrieves the history of client secret requests for a given URL and method.
@@ -953,20 +963,20 @@ declare class Skapi {
      * Lists consumed tickets with optional filters and pagination.
      * @param params Request parameters.
      * @param fetchOptions Pagination and fetch behavior options.
-     * @returns A promise that resolves to Promise<DatabaseResponse<any[]>>.
+     * @returns A promise that resolves to Promise<DatabaseResponse<any>>.
      */
     getConsumedTickets(params: {
         ticket_id?: string;
-    }, fetchOptions?: FetchOptions): Promise<DatabaseResponse<any[]>>;
+    }, fetchOptions?: FetchOptions): Promise<DatabaseResponse<any>>;
     /**
      * Lists issued tickets with optional filters and pagination.
      * @param params Request parameters.
      * @param fetchOptions Pagination and fetch behavior options.
-     * @returns A promise that resolves to Promise<DatabaseResponse<any[]>>.
+     * @returns A promise that resolves to Promise<DatabaseResponse<any>>.
      */
     getTickets(params: {
         ticket_id?: string;
-    }, fetchOptions?: FetchOptions): Promise<DatabaseResponse<any[]>>;
+    }, fetchOptions?: FetchOptions): Promise<DatabaseResponse<any>>;
     /**
      * Closes the active realtime WebSocket connection.
      * @returns A promise that resolves to Promise<void>.
@@ -974,12 +984,12 @@ declare class Skapi {
     closeRealtime(): Promise<void>;
     /**
      * Fetches currently connected users in a realtime group.
-     * @param params Request parameters.
+     * @param params Request parameters. When `group` is omitted, it defaults to the realtime group the user is currently joined to.
      * @param fetchOptions Pagination and fetch behavior options.
      * @returns A promise that resolves to Promise<DatabaseResponse<{ user_id: string; cid: string }[]>>.
      */
-    getRealtimeUsers(params: {
-        group: string;
+    getRealtimeUsers(params?: {
+        group?: string;
         user_id?: string;
     }, fetchOptions?: FetchOptions): Promise<DatabaseResponse<{
         user_id: string;
@@ -1024,11 +1034,11 @@ declare class Skapi {
      * Invites a user by email with optional attributes and invitation email options.
      * @param params Payload for the request.
      * @param options Optional behavior configuration.
-     * @returns A promise that resolves to Promise<'SUCCESS: Invitation has been sent.'>.
+     * @returns A promise that resolves to Promise<'SUCCESS: Invitation has been sent. (User ID: xxx...)'>.
      */
     inviteUser(params: UserAttributes & {
-        openid_id: string;
-        access_group: number;
+        openid_id?: string;
+        access_group?: number;
     }, options?: {
         confirmation_url?: string;
         email_subscription?: boolean;
@@ -1036,15 +1046,16 @@ declare class Skapi {
             url: string;
             subject: string;
         };
-    }): Promise<'SUCCESS: Invitation has been sent.'>;
+    }): Promise<'SUCCESS: Invitation has been sent. (User ID: xxx...)'>;
     /**
      * Creates a user account directly from admin context.
      * @param params Payload for the request.
      * @returns A promise that resolves to Promise<UserProfile & { email_admin: string; username: string; }>.
      */
     createAccount(params: UserAttributes & {
+        email: string;
         password: string;
-        access_group: number;
+        access_group?: number;
     }): Promise<UserProfile & {
         email_admin: string;
         username: string;
@@ -1066,9 +1077,9 @@ declare class Skapi {
      */
     getRealtimeGroups(params?: {
         /** Index name to search. */
-        searchFor: 'group' | 'number_of_users';
+        searchFor?: 'group' | 'number_of_users';
         /** Index value to search. */
-        value: string | number;
+        value?: string | number;
         /** Search condition. */
         condition?: '>' | '>=' | '=' | '<' | '<=' | '!=' | 'gt' | 'gte' | 'eq' | 'lt' | 'lte' | 'ne';
         /** Range of search. */
@@ -1111,7 +1122,7 @@ declare class Skapi {
      * @returns A promise that resolves to Promise<UserProfile | null>.
      */
     getProfile(options?: {
-        refreshToken: boolean;
+        refreshToken?: boolean;
     }): Promise<UserProfile | null>;
     /**
      * Retrieves a file by URL with optional conversion mode, expiration, and progress handling.
@@ -1164,9 +1175,9 @@ declare class Skapi {
      * @returns A promise that resolves to Promise<DatabaseResponse<Table>>.
      */
     getTables(
-    /** If null fetch all list of tables. */
-    query: {
-        table: string;
+    /** If omitted, fetches the full list of tables. */
+    query?: {
+        table?: string;
         /** Condition operator of table name. */
         condition?: Condition;
     }, fetchOptions?: FetchOptions): Promise<DatabaseResponse<Table>>;
@@ -1184,7 +1195,7 @@ declare class Skapi {
         /** Queries order by */
         order?: {
             /** Key name to order by. */
-            by: 'average_number' | 'total_number' | 'number_count' | 'average_bool' | 'total_bool' | 'bool_count' | 'string_count' | 'index_name';
+            by: 'average_number' | 'total_number' | 'number_count' | 'average_bool' | 'total_bool' | 'bool_count' | 'string_count' | 'index_name' | 'number_of_records';
             /** Value to query. */
             value?: number | boolean | string;
             condition?: Condition;
@@ -1196,9 +1207,9 @@ declare class Skapi {
      * @param fetchOptions Pagination and fetch behavior options.
      * @returns A promise that resolves to Promise<DatabaseResponse<Tag>>.
      */
-    getTags(query: {
+    getTags(query?: {
         /** Table name */
-        table: string;
+        table?: string;
         /** Tag name */
         tag?: string;
         /** String query condition for tag name. */
@@ -1234,13 +1245,13 @@ declare class Skapi {
      */
     getUsers(params?: {
         /** Index name to search. */
-        searchFor: 'user_id' | 'email' | 'phone_number' | 'locale' | 'name' | 'address' | 'gender' | 'birthdate' | 'subscribers' | 'timestamp' | 'approved';
+        searchFor: 'user_id' | 'email' | 'phone_number' | 'locale' | 'name' | 'address' | 'gender' | 'birthdate' | 'subscribers' | 'timestamp' | 'access_group' | 'approved';
         /** Index value to search. */
-        value: string | number | boolean | string[];
+        value: string | number | string[];
         /** Search condition. */
         condition?: '>' | '>=' | '=' | '<' | '<=' | 'gt' | 'gte' | 'eq' | 'lt' | 'lte';
         /** Range of search. */
-        range?: string | number | boolean;
+        range?: string | number;
     }, fetchOptions?: FetchOptions): Promise<DatabaseResponse<UserPublic>>;
     /**
      * Disables the currently logged-in user account.
@@ -1261,7 +1272,7 @@ declare class Skapi {
      * @returns A promise that resolves to Promise<string>.
      */
     unsubscribeNewsletter(params: {
-        group: number | 'public' | 'authorized' | null;
+        group: number | 'public' | 'authorized' | 'admin';
     }): Promise<string>;
     /**
      * Registers a web push subscription endpoint for notifications.
@@ -1312,9 +1323,9 @@ declare class Skapi {
          * 'message_id' and 'subject' value should be string.<br>
          * Others numbers.
          */
-        searchFor: 'message_id' | 'timestamp' | 'read' | 'complaint' | 'subject';
+        searchFor: 'message_id' | 'timestamp' | 'read' | 'complaint' | 'bounced' | 'subject';
         value: string | number;
-        range: string | number;
+        range?: string | number;
         /**
          * Defaults to '=',
          * Condition does not work with range.
@@ -1330,12 +1341,18 @@ declare class Skapi {
      */
     getNewsletterSubscription(params: {
         group?: number | 'public' | 'authorized';
+        user_id?: string;
     }, fetchOptions?: FetchOptions): Promise<{
         active: boolean;
         timestamp: number;
         group: number;
         subscribed_email: string;
-    }[]>;
+    }[] | DatabaseResponse<{
+        active: boolean;
+        timestamp: number;
+        group: number;
+        subscribed_email: string;
+    }>>;
     /**
      * Requests a username change confirmation flow for the current user.
      * @param params Request parameters.
@@ -1553,7 +1570,7 @@ declare class Skapi {
     /**
      * Creates or updates a database record with optional file uploads.
      * @param params Payload for the request.
-     * @param config Additional configuration options.
+     * @param config Required record configuration (table, record_id, index, tags, source, reference, etc.).
      * @param files File list to process.
      * @returns A promise that resolves to Promise<RecordData>.
      */
@@ -1562,7 +1579,7 @@ declare class Skapi {
         file: File;
     }[]): Promise<RecordData>;
     /**
-     * Fetches subscriber/subscription relationships with filters and pagination.
+     * Fetches subscriber/subscription relationships with filters and pagination. At least one of `subscriber` or `subscription` must be provided.
      * @param params Request parameters.
      * @param fetchOptions Pagination and fetch behavior options.
      * @returns A promise that resolves to Promise<DatabaseResponse<Subscription>>.
@@ -1616,10 +1633,15 @@ declare class Skapi {
      * @returns A promise that resolves to Promise<string>.
      */
     subscribeNewsletter(params: Form<{
-        email?: string;
-        group: number | 'public' | 'authorized' | 'admin';
+        email?: string | string[];
+        group: number | 'public' | 'authorized' | 'admin' | (string & {});
         redirect?: string;
     }>): Promise<string>;
+    /**
+     * Creates or updates multiple database records in a single bulk request. Requires a non-empty array, and all entries must share the same table/service.
+     * @param config Non-empty array of record configurations to post.
+     * @returns A promise that resolves to Promise<RecordData[]>.
+     */
     bulkPostRecords(config: PostRecordConfig[]): Promise<RecordData[]>;
 }