@iglo.tech/iglo.base 0.0.0-stage → 1.0.1-rc.0

package/dist/types/src/services/RealtimeService.d.ts

@@ -0,0 +1,124 @@
+import type { Loose } from "../tools/loose.js";
+import { BaseService } from "./BaseService.js";
+import { type SendOptions } from "../tools/options.js";
+export type UnsubscribeFunc = () => Promise<void>;
+export declare class RealtimeService extends BaseService {
+    clientId: string;
+    private eventSource;
+    private subscriptions;
+    private lastSentSubscriptions;
+    private connectTimeoutId?;
+    private maxConnectTimeout;
+    private reconnectTimeoutId?;
+    private reconnectAttempts;
+    private maxReconnectAttempts;
+    private predefinedReconnectIntervals;
+    private pendingConnects;
+    private pendingSubmits;
+    private isProcessingPendingSubmits;
+    private connectionGeneration;
+    /**
+     * Returns whether the realtime connection has been established.
+     */
+    get isConnected(): boolean;
+    /**
+     * An optional hook that is invoked when the realtime client disconnects
+     * either when unsubscribing from all subscriptions or when the
+     * connection was interrupted or closed by the server.
+     *
+     * The received argument could be used to determine whether the disconnect
+     * is a result from unsubscribing (`activeSubscriptions.length == 0`)
+     * or because of network/server error (`activeSubscriptions.length > 0`).
+     *
+     * If you want to listen for the opposite, aka. when the client connection is established,
+     * subscribe to the `PB_CONNECT` event.
+     */
+    onDisconnect?: (activeSubscriptions: Array<string>) => void;
+    /**
+     * Register the subscription listener.
+     *
+     * You can subscribe multiple times to the same topic.
+     *
+     * If the SSE connection is not started yet,
+     * this method will also initialize it.
+     */
+    subscribe(topic: string, callback: (data: Loose) => void, options?: SendOptions): Promise<UnsubscribeFunc>;
+    /**
+     * Sends the current subscriptions again, with the client's current authorization. Upstream
+     * keeps a subscription's auth state on the server, so a new token for the same record is
+     * accepted and replaces it (docs/design/13-ssr.md, "Browser client and realtime"). A no-op
+     * when the connection is not established or there are no subscriptions.
+     */
+    resubmit(): Promise<void>;
+    /**
+     * Closes the SSE connection and opens a new one with the same subscriptions, after an intended
+     * change of authorization. The new connection gets its own client ID, and the subscriptions are
+     * sent on it with the client's current authorization. Upstream keeps a connection's
+     * authorization on the server and only accepts a change to the same record (a guest may then
+     * sign in), so a different user or a sign-out needs a new connection
+     * (docs/design/13-ssr.md, "Browser client and realtime").
+     *
+     * The new connection is opened the way a dropped one is reopened: its first attempt waits the
+     * first backoff step, and a failed attempt retries in the background with the usual backoff
+     * (`connectErrorHandler`). Unlike a dropped connection, it does not call `onDisconnect`, since
+     * nothing went wrong on the network or the server. The returned promise resolves when the
+     * reconnect is scheduled, not when the new connection is up. A no-op without subscriptions.
+     */
+    reconnect(): Promise<void>;
+    /**
+     * Unsubscribe from all subscription listeners with the specified topic.
+     *
+     * If `topic` is not provided, then this method will unsubscribe
+     * from all active subscriptions.
+     *
+     * This method is no-op if there are no active subscriptions.
+     *
+     * The related sse connection will be autoclosed if after the
+     * unsubscribe operation there are no active subscriptions left.
+     */
+    unsubscribe(topic?: string): Promise<void>;
+    /**
+     * Unsubscribe from all subscription listeners starting with the specified topic prefix.
+     *
+     * This method is no-op if there are no active subscriptions with the specified topic prefix.
+     *
+     * The related sse connection will be autoclosed if after the
+     * unsubscribe operation there are no active subscriptions left.
+     */
+    unsubscribeByPrefix(keyPrefix: string): Promise<void>;
+    /**
+     * Unsubscribe from all subscriptions matching the specified topic and listener function.
+     *
+     * This method is no-op if there are no active subscription with
+     * the specified topic and listener.
+     *
+     * The related sse connection will be autoclosed if after the
+     * unsubscribe operation there are no active subscriptions left.
+     */
+    unsubscribeByTopicAndListener(topic: string, listener: EventListener): Promise<void>;
+    private hasSubscriptionListeners;
+    private submitSubscriptions;
+    private finalizePendingSubscriptions;
+    private getSubscriptionsCancelKey;
+    private getSubscriptionsByTopic;
+    private getNonEmptySubscriptionKeys;
+    private hasUnsentSubscriptions;
+    private sendSubscriptions;
+    private addAllSubscriptionListeners;
+    private removeAllSubscriptionListeners;
+    private connect;
+    private initConnect;
+    private connectErrorHandler;
+    /**
+     * Schedules the next connection attempt after the backoff step for the current attempt count,
+     * and counts the attempt. Shared by a dropped connection and by `reconnect()`, so both retry
+     * the same way.
+     */
+    private scheduleReconnect;
+    /**
+     * Closes the connection. `fromReconnect` keeps the reconnect attempts and the pending connects,
+     * for a retry. `notify` is false when the close is intended (a `reconnect()`), so the
+     * `onDisconnect` hook, which means a network or server error, is not called.
+     */
+    private disconnect;
+}

package/dist/types/src/services/RecordService.d.ts

@@ -0,0 +1,374 @@
+import type { Loose, LooseObject } from "../tools/loose.js";
+import Client from "../Client.js";
+import { type UnsubscribeFunc } from "./RealtimeService.js";
+import { CrudService } from "./CrudService.js";
+import { type ListResult, type RecordModel } from "../tools/dtos.js";
+import { type CommonOptions, type RecordFullListOptions, type RecordListOptions, type RecordOptions, type SendOptions, type RecordSubscribeOptions } from "../tools/options.js";
+export interface RecordAuthResponse<T = RecordModel> {
+    /**
+     * The signed PocketBase auth record.
+     */
+    record: T;
+    /**
+     * The PocketBase record auth token.
+     *
+     * If you are looking for the OAuth2 access and refresh tokens
+     * they are available under the `meta.accessToken` and `meta.refreshToken` props.
+     */
+    token: string;
+    /**
+     * Auth meta data usually filled when OAuth2 is used.
+     */
+    meta?: LooseObject;
+}
+export interface AuthProviderInfo {
+    name: string;
+    displayName: string;
+    state: string;
+    authURL: string;
+    codeVerifier: string;
+    codeChallenge: string;
+    codeChallengeMethod: string;
+}
+export interface AuthMethodsList {
+    mfa: {
+        enabled: boolean;
+        duration: number;
+    };
+    otp: {
+        enabled: boolean;
+        duration: number;
+    };
+    password: {
+        enabled: boolean;
+        identityFields: Array<string>;
+    };
+    oauth2: {
+        enabled: boolean;
+        providers: Array<AuthProviderInfo>;
+    };
+}
+export interface RecordSubscription<T = RecordModel> {
+    action: string;
+    record: T;
+}
+export type OAuth2UrlCallback = (url: string) => void | Promise<void>;
+export interface OAuth2AuthConfig extends SendOptions {
+    provider: string;
+    scopes?: Array<string>;
+    createData?: LooseObject;
+    urlCallback?: OAuth2UrlCallback;
+    query?: RecordOptions;
+}
+export interface OTPResponse {
+    otpId: string;
+}
+export declare class RecordService<M = RecordModel> extends CrudService<M> {
+    readonly collectionIdOrName: string;
+    constructor(client: Client, collectionIdOrName: string);
+    /**
+     * @inheritdoc
+     */
+    get baseCrudPath(): string;
+    /**
+     * Returns the current collection service base path.
+     */
+    get baseCollectionPath(): string;
+    /**
+     * Returns whether the current service collection is superusers.
+     */
+    get isSuperusers(): boolean;
+    /**
+     * Subscribe to realtime changes to the specified topic ("*" or record id).
+     *
+     * If `topic` is the wildcard "*", then this method will subscribe to
+     * any record changes in the collection.
+     *
+     * If `topic` is a record id, then this method will subscribe only
+     * to changes of the specified record id.
+     *
+     * It's OK to subscribe multiple times to the same topic.
+     * You can use the returned `UnsubscribeFunc` to remove only a single subscription.
+     * Or use `unsubscribe(topic)` if you want to remove all subscriptions attached to the topic.
+     */
+    subscribe<T = M>(topic: string, callback: (data: RecordSubscription<T>) => void, options?: RecordSubscribeOptions): Promise<UnsubscribeFunc>;
+    /**
+     * Unsubscribe from all subscriptions of the specified topic
+     * ("*" or record id).
+     *
+     * If `topic` is not set, then this method will unsubscribe from
+     * all subscriptions associated to the current collection.
+     */
+    unsubscribe(topic?: string): Promise<void>;
+    /**
+     * @inheritdoc
+     */
+    getFullList<T = M>(options?: RecordFullListOptions): Promise<Array<T>>;
+    /**
+     * @inheritdoc
+     */
+    getFullList<T = M>(batch?: number, options?: RecordListOptions): Promise<Array<T>>;
+    /**
+     * @inheritdoc
+     */
+    getList<T = M>(page?: number, perPage?: number, options?: RecordListOptions): Promise<ListResult<T>>;
+    /**
+     * @inheritdoc
+     */
+    getFirstListItem<T = M>(filter: string, options?: RecordListOptions): Promise<T>;
+    /**
+     * @inheritdoc
+     */
+    getOne<T = M>(id: string, options?: RecordOptions): Promise<T>;
+    /**
+     * @inheritdoc
+     */
+    create<T = M>(bodyParams?: LooseObject | FormData, options?: RecordOptions): Promise<T>;
+    /**
+     * @inheritdoc
+     *
+     * If the current `client.authStore.record` matches with the updated id, then
+     * on success the `client.authStore.record` will be updated with the new response record fields.
+     */
+    update<T = M>(id: string, bodyParams?: LooseObject | FormData, options?: RecordOptions): Promise<T>;
+    /**
+     * @inheritdoc
+     *
+     * If the current `client.authStore.record` matches with the deleted id,
+     * then on success the `client.authStore` will be cleared.
+     */
+    delete(id: string, options?: CommonOptions): Promise<boolean>;
+    /**
+     * Prepare successful collection authorization response.
+     */
+    protected authResponse<T = M>(responseData: LooseObject): RecordAuthResponse<T>;
+    /**
+     * Returns all available collection auth methods.
+     *
+     * @throws {ClientResponseError}
+     */
+    listAuthMethods(options?: CommonOptions): Promise<AuthMethodsList>;
+    /**
+     * Authenticate a single auth collection record via its username/email and password.
+     *
+     * On success, this method also automatically updates
+     * the client's AuthStore data and returns:
+     * - the authentication token
+     * - the authenticated record model
+     *
+     * @throws {ClientResponseError}
+     */
+    authWithPassword<T = M>(usernameOrEmail: string, password: string, options?: RecordOptions): Promise<RecordAuthResponse<T>>;
+    /**
+     * Authenticate a single auth collection record with OAuth2 code.
+     *
+     * If you don't have an OAuth2 code you may also want to check `authWithOAuth2` method.
+     *
+     * On success, this method also automatically updates
+     * the client's AuthStore data and returns:
+     * - the authentication token
+     * - the authenticated record model
+     * - the OAuth2 account data (eg. name, email, avatar, etc.)
+     *
+     * @throws {ClientResponseError}
+     */
+    authWithOAuth2Code<T = M>(provider: string, code: string, codeVerifier: string, redirectURL: string, createData?: LooseObject, options?: RecordOptions): Promise<RecordAuthResponse<T>>;
+    /**
+     * @deprecated
+     * Consider using authWithOAuth2Code(provider, code, codeVerifier, redirectURL, createdData, options?).
+     */
+    authWithOAuth2Code<T = M>(provider: string, code: string, codeVerifier: string, redirectURL: string, createData?: LooseObject, body?: Loose, query?: Loose): Promise<RecordAuthResponse<T>>;
+    /**
+     * @deprecated This form of authWithOAuth2 is deprecated.
+     *
+     * Please use `authWithOAuth2Code()` OR its simplified realtime version
+     * as shown in https://pocketbase.io/docs/authentication/#oauth2-integration.
+     */
+    authWithOAuth2<T = M>(provider: string, code: string, codeVerifier: string, redirectURL: string, createData?: LooseObject, bodyParams?: LooseObject, queryParams?: RecordOptions): Promise<RecordAuthResponse<T>>;
+    /**
+     * Authenticate a single auth collection record with OAuth2
+     * **without custom redirects, deeplinks or even page reload**.
+     *
+     * This method initializes a one-off realtime subscription and will
+     * open a popup window with the OAuth2 vendor page to authenticate.
+     * Once the external OAuth2 sign-in/sign-up flow is completed, the popup
+     * window will be automatically closed and the OAuth2 data sent back
+     * to the user through the previously established realtime connection.
+     *
+     * You can specify an optional `urlCallback` prop to customize
+     * the default url `window.open` behavior.
+     *
+     * On success, this method also automatically updates
+     * the client's AuthStore data and returns:
+     * - the authentication token
+     * - the authenticated record model
+     * - the OAuth2 account data (eg. name, email, avatar, etc.)
+     *
+     * Example:
+     *
+     * ```js
+     * const authData = await pb.collection("users").authWithOAuth2({
+     *     provider: "google",
+     * })
+     * ```
+     *
+     * Note1: When creating the OAuth2 app in the provider dashboard
+     * you have to configure `https://yourdomain.com/api/oauth2-redirect`
+     * as redirect URL.
+     *
+     * Note2: Safari may block the default `urlCallback` popup because
+     * it doesn't allow `window.open` calls as part of an `async` click functions.
+     * To workaround this you can either change your click handler to not be marked as `async`
+     * OR manually call `window.open` before your `async` function and use the
+     * window reference in your own custom `urlCallback` (see https://github.com/pocketbase/pocketbase/discussions/2429#discussioncomment-5943061).
+     * For example:
+     * ```js
+     * <button id="btn">Login with Gitlab</button>
+     * ...
+     * document.getElementById("btn").addEventListener("click", () => {
+     *     pb.collection("users").authWithOAuth2({
+     *         provider: "gitlab",
+     *     }).then((authData) => {
+     *         console.log(authData)
+     *     }).catch((err) => {
+     *         console.log(err, err.originalError);
+     *     });
+     * })
+     * ```
+     *
+     * @throws {ClientResponseError}
+     */
+    authWithOAuth2<T = M>(options: OAuth2AuthConfig): Promise<RecordAuthResponse<T>>;
+    /**
+     * Refreshes the current authenticated record instance and
+     * returns a new token and record data.
+     *
+     * On success this method also automatically updates the client's AuthStore.
+     *
+     * @throws {ClientResponseError}
+     */
+    authRefresh<T = M>(options?: RecordOptions): Promise<RecordAuthResponse<T>>;
+    /**
+     * @deprecated
+     * Consider using authRefresh(options?).
+     */
+    authRefresh<T = M>(body?: Loose, query?: Loose): Promise<RecordAuthResponse<T>>;
+    /**
+     * Sends auth record password reset request.
+     *
+     * @throws {ClientResponseError}
+     */
+    requestPasswordReset(email: string, options?: CommonOptions): Promise<boolean>;
+    /**
+     * @deprecated
+     * Consider using requestPasswordReset(email, options?).
+     */
+    requestPasswordReset(email: string, body?: Loose, query?: Loose): Promise<boolean>;
+    /**
+     * Confirms auth record password reset request.
+     *
+     * @throws {ClientResponseError}
+     */
+    confirmPasswordReset(passwordResetToken: string, password: string, passwordConfirm: string, options?: CommonOptions): Promise<boolean>;
+    /**
+     * @deprecated
+     * Consider using confirmPasswordReset(passwordResetToken, password, passwordConfirm, options?).
+     */
+    confirmPasswordReset(passwordResetToken: string, password: string, passwordConfirm: string, body?: Loose, query?: Loose): Promise<boolean>;
+    /**
+     * Sends auth record verification email request.
+     *
+     * @throws {ClientResponseError}
+     */
+    requestVerification(email: string, options?: CommonOptions): Promise<boolean>;
+    /**
+     * @deprecated
+     * Consider using requestVerification(email, options?).
+     */
+    requestVerification(email: string, body?: Loose, query?: Loose): Promise<boolean>;
+    /**
+     * Confirms auth record email verification request.
+     *
+     * If the current `client.authStore.record` matches with the auth record from the token,
+     * then on success the `client.authStore.record.verified` will be updated to `true`.
+     *
+     * @throws {ClientResponseError}
+     */
+    confirmVerification(verificationToken: string, options?: CommonOptions): Promise<boolean>;
+    /**
+     * @deprecated
+     * Consider using confirmVerification(verificationToken, options?).
+     */
+    confirmVerification(verificationToken: string, body?: Loose, query?: Loose): Promise<boolean>;
+    /**
+     * Sends an email change request to the authenticated record model.
+     *
+     * @throws {ClientResponseError}
+     */
+    requestEmailChange(newEmail: string, options?: CommonOptions): Promise<boolean>;
+    /**
+     * @deprecated
+     * Consider using requestEmailChange(newEmail, options?).
+     */
+    requestEmailChange(newEmail: string, body?: Loose, query?: Loose): Promise<boolean>;
+    /**
+     * Confirms auth record's new email address.
+     *
+     * If the current `client.authStore.record` matches with the auth record from the token,
+     * then on success the `client.authStore` will be cleared.
+     *
+     * @throws {ClientResponseError}
+     */
+    confirmEmailChange(emailChangeToken: string, password: string, options?: CommonOptions): Promise<boolean>;
+    /**
+     * @deprecated
+     * Consider using confirmEmailChange(emailChangeToken, password, options?).
+     */
+    confirmEmailChange(emailChangeToken: string, password: string, body?: Loose, query?: Loose): Promise<boolean>;
+    /**
+     * @deprecated use collection("_externalAuths").*
+     *
+     * Lists all linked external auth providers for the specified auth record.
+     *
+     * @throws {ClientResponseError}
+     */
+    listExternalAuths(recordId: string, options?: CommonOptions): Promise<Array<RecordModel>>;
+    /**
+     * @deprecated use collection("_externalAuths").*
+     *
+     * Unlink a single external auth provider from the specified auth record.
+     *
+     * @throws {ClientResponseError}
+     */
+    unlinkExternalAuth(recordId: string, provider: string, options?: CommonOptions): Promise<boolean>;
+    /**
+     * Sends auth record OTP to the provided email.
+     *
+     * @throws {ClientResponseError}
+     */
+    requestOTP(email: string, options?: CommonOptions): Promise<OTPResponse>;
+    /**
+     * Authenticate a single auth collection record via OTP.
+     *
+     * On success, this method also automatically updates
+     * the client's AuthStore data and returns:
+     * - the authentication token
+     * - the authenticated record model
+     *
+     * @throws {ClientResponseError}
+     */
+    authWithOTP<T = M>(otpId: string, password: string, options?: CommonOptions): Promise<RecordAuthResponse<T>>;
+    /**
+     * Impersonate authenticates with the specified recordId and
+     * returns a new client with the received auth token in a memory store.
+     *
+     * If `duration` is 0 the generated auth token will fallback
+     * to the default collection auth token duration.
+     *
+     * This action currently requires superusers privileges.
+     *
+     * @throws {ClientResponseError}
+     */
+    impersonate(recordId: string, duration: number, options?: CommonOptions): Promise<Client>;
+    private _replaceQueryParams;
+}

package/dist/types/src/services/SQLService.d.ts

@@ -0,0 +1,21 @@
+import { BaseService } from "./BaseService.js";
+import { type CommonOptions } from "../tools/options.js";
+export interface SQLResult {
+    execTime: number;
+    affectedRows: number;
+    columns: Array<{
+        name: string;
+        type: string;
+        nullable: boolean;
+    }>;
+    rows: Array<Array<string | null>>;
+}
+export declare class SQLService extends BaseService {
+    /**
+     * Executes the specified raw SQL query.
+     * This operation is allowed only for superusers.
+     *
+     * @throws {ClientResponseError}
+     */
+    run(query: string, options?: CommonOptions): Promise<SQLResult>;
+}

package/dist/types/src/services/SettingsService.d.ts

@@ -0,0 +1,46 @@
+import type { LooseObject } from "../tools/loose.js";
+import { BaseService } from "./BaseService.js";
+import { type CommonOptions } from "../tools/options.js";
+interface appleClientSecret {
+    secret: string;
+}
+export declare class SettingsService extends BaseService {
+    /**
+     * Fetch all available app settings.
+     *
+     * @throws {ClientResponseError}
+     */
+    getAll(options?: CommonOptions): Promise<LooseObject>;
+    /**
+     * Bulk updates app settings.
+     *
+     * @throws {ClientResponseError}
+     */
+    update(bodyParams?: LooseObject | FormData, options?: CommonOptions): Promise<LooseObject>;
+    /**
+     * Performs a S3 filesystem connection test.
+     *
+     * The currently supported `filesystem` are "storage" and "backups".
+     *
+     * @throws {ClientResponseError}
+     */
+    testS3(filesystem?: string, options?: CommonOptions): Promise<boolean>;
+    /**
+     * Sends a test email.
+     *
+     * The possible `emailTemplate` values are:
+     * - verification
+     * - password-reset
+     * - email-change
+     *
+     * @throws {ClientResponseError}
+     */
+    testEmail(collectionIdOrName: string, toEmail: string, emailTemplate: string, options?: CommonOptions): Promise<boolean>;
+    /**
+     * Generates a new Apple OAuth2 client secret.
+     *
+     * @throws {ClientResponseError}
+     */
+    generateAppleClientSecret(clientId: string, teamId: string, keyId: string, privateKey: string, duration: number, options?: CommonOptions): Promise<appleClientSecret>;
+}
+export {};