@liveblocks/node 1.2.0-internal3 → 1.2.0-internal5

package/dist/index.d.mts

@@ -0,0 +1,339 @@
+import { IncomingHttpHeaders } from 'http';
+
+/**
+ * TODO Officially mark as DEPRECATED, point to migration guide.
+ */
+declare type AuthorizeOptions = {
+    /**
+     * The secret API key for your Liveblocks account. You can find it on
+     * https://liveblocks.io/dashboard/apikeys
+     */
+    secret: string;
+    /**
+     * The room ID for which to authorize the user. This will authorize the user
+     * to enter the Liveblocks room.
+     */
+    room: string;
+    /**
+     * Associates a user ID to the session that is being authorized. The user ID
+     * is typically set to the user ID from your own database.
+     *
+     * It can also be used to generate a token that gives access to a private
+     * room where the userId is configured in the room accesses.
+     *
+     * This user ID will be used as the unique identifier to compute your
+     * Liveblocks account's Monthly Active Users.
+     */
+    userId: string;
+    /**
+     * Arbitrary metadata associated to this user session.
+     *
+     * You can use it to store a small amount of static metadata for a user
+     * session. It is public information, that will be visible to other users in
+     * the same room, like name, avatar URL, etc.
+     *
+     * It's only suitable for static info that won't change during a session. If
+     * you want to store dynamic metadata on a user session, don't keep that in
+     * the session token, but use Presence instead.
+     *
+     * Can't exceed 1KB when serialized as JSON.
+     */
+    userInfo?: unknown;
+    /**
+     * Tell Liveblocks which group IDs this user belongs to. This will authorize
+     * the user session to access private rooms that have at least one of these
+     * group IDs listed in their room access configuration.
+     *
+     * See https://liveblocks.io/docs/guides/managing-rooms-users-permissions#permissions
+     * for how to configure your room's permissions to use this feature.
+     */
+    groupIds?: string[];
+};
+/**
+ * TODO Officially mark as DEPRECATED, point to migration guide.
+ */
+declare type AuthorizeResponse = {
+    status: number;
+    body: string;
+    error?: Error;
+};
+/**
+ * TODO Officially mark as DEPRECATED, point to migration guide.
+ *
+ * Tells Liveblocks that a user should be allowed access to a room, which user
+ * this session is for, and what metadata to associate with the user (like
+ * name, avatar, etc.)
+ *
+ * @example
+ * export default async function auth(req, res) {
+ *
+ * // Implement your own security here.
+ *
+ * const room = req.body.room;
+ * const response = await authorize({
+ *   room,
+ *   secret,
+ *   userId: "123",
+ *   userInfo: {    // Optional
+ *     name: "Ada Lovelace"
+ *   },
+ *   groupIds: ["group1"] // Optional
+ * });
+ * return res.status(response.status).end(response.body);
+ * }
+ */
+declare function authorize(options: AuthorizeOptions): Promise<AuthorizeResponse>;
+
+declare const ALL_PERMISSIONS: readonly ["room:write", "room:read", "room:presence:write", "comments:write", "comments:read"];
+declare type Permission = (typeof ALL_PERMISSIONS)[number];
+/**
+ * Class to help you construct the exact permission set to grant a user, used
+ * when making `.authorizeUser()` calls.
+ *
+ * Usage:
+ *
+ *    const session = liveblocks.prepareSession();
+ *    session.allow(roomId, permissions)  // or...
+ *
+ * For the `permissions` argument, you can pass a list of specific permissions,
+ * or use one of our presets:
+ *
+ *    session.allow('my-room', session.FULL_ACCESS)  // Read + write access to room storage and comments
+ *    session.allow('my-room', session.READ_ACCESS)  // Read-only access to room storage and comments
+ *
+ * Rooms can be specified with a prefix match, if the name ends in an asterisk.
+ * In that case, access is granted to *all* rooms that start with that prefix:
+ *
+ *    // Read + write access to *all* rooms that start with "abc:"
+ *    session.allow('abc:*', session.FULL_ACCESS)
+ *
+ * You can define at most 10 room IDs (or patterns) in a single token,
+ * otherwise the token would become too large and unwieldy.
+ *
+ * All permissions granted are additive. You cannot "remove" permissions once
+ * you grant them. For example:
+ *
+ *    session
+ *      .allow('abc:*',   session.FULL_ACCESS)
+ *      .allow('abc:123', session.READ_ACCESS)
+ *
+ * Here, room `abc:123` would have full access. The second .allow() call only
+ * _adds_ read permissions, but that has no effect since full access
+ * permissions were already added to the set.
+ */
+declare class Session {
+    readonly FULL_ACCESS: readonly ["room:write", "comments:write"];
+    readonly READ_ACCESS: readonly ["room:read", "room:presence:write", "comments:read"];
+    allow(roomIdOrPattern: string, newPerms: readonly Permission[]): this;
+    /**
+     * Call this to authorize the session to access Liveblocks. Note that this
+     * will return a Liveblocks "access token". Anyone that obtains such access
+     * token will have access to the allowed resources.
+     */
+    authorize(): Promise<AuthResponse>;
+}
+
+declare type LiveblocksOptions = {
+    /**
+     * The Liveblocks secret key. Must start with "sk_".
+     * Get it from https://liveblocks.io/dashboard/apikeys
+     */
+    secret: string;
+};
+declare type CreateSessionOptions = {
+    userInfo: unknown;
+};
+declare type AuthResponse = {
+    status: number;
+    body: string;
+    error?: Error;
+};
+declare type Identity = {
+    userId: string;
+    groupIds: string[];
+};
+/**
+ * Interact with the Liveblocks API from your Node.js backend.
+ */
+declare class Liveblocks {
+    /**
+     * Interact with the Liveblocks API from your Node.js backend.
+     */
+    constructor(options: LiveblocksOptions);
+    /**
+     * Prepares a new session to authorize a user to access Liveblocks.
+     *
+     * IMPORTANT:
+     * Always make sure that you trust the user making the request to your
+     * backend before calling .prepareSession()!
+     *
+     * @param userId Tell Liveblocks the user ID of the user to authorize. Must
+     * uniquely identify the user account in your system. The uniqueness of this
+     * value will determine how many MAUs will be counted/billed.
+     *
+     * @param options.userInfo Custom metadata to attach to this user. Data you
+     * add here will be visible to all other clients in the room, through the
+     * `other.info` property.
+     *
+     */
+    prepareSession(userId: string, options?: CreateSessionOptions): Session;
+    /**
+     * Call this to authenticate the user as an actor you want to allow to use
+     * Liveblocks.
+     *
+     * You should use this method only if you want to manage your permissions
+     * through the Liveblocks Permissions API. This method is more complicated to
+     * set up, but allows for finer-grained specification of permissions.
+     *
+     * Calling `.identifyUser()` only lets you securely identify a user (and what
+     * groups they belong to). What permissions this user will end up having is
+     * determined by whatever permissions you assign the user/group in your
+     * Liveblocks account, through the Permissions API:
+     * https://liveblocks.io/docs/rooms/permissions
+     *
+     * IMPORTANT:
+     * Always verify that you trust the user making the request before calling
+     * .identifyUser()!
+     *
+     * @param identity Tell Liveblocks the user ID of the user to authenticate.
+     * Must uniquely identify the user account in your system. The uniqueness of
+     * this value will determine how many MAUs will be counted/billed.
+     *
+     * If you also want to assign which groups this user belongs to, use the
+     * object form and specify the `groupIds` property. Those `groupIds` should
+     * match the groupIds you assigned permissions to via the Liveblocks
+     * Permissions API, see
+     * https://liveblocks.io/docs/rooms/permissions#permissions-levels-groups-accesses-example
+     *
+     * @param options.userInfo Custom metadata to attach to this user. Data you
+     * add here will be visible to all other clients in the room, through the
+     * `other.info` property.
+     */
+    identifyUser(identity: string | Identity, options?: {
+        userInfo: unknown;
+    }): Promise<AuthResponse>;
+}
+
+declare class WebhookHandler {
+    private secretBuffer;
+    private static secretPrefix;
+    constructor(
+    /**
+     * The signing secret provided on the dashboard's webhooks page
+     * @example "whsec_wPbvQ+u3VtN2e2tRPDKchQ1tBZ3svaHLm"
+     */
+    secret: string);
+    /**
+     * Verifies a webhook request and returns the event
+     */
+    verifyRequest(request: WebhookRequest): WebhookEvent;
+    /**
+     * Verifies the headers and returns the webhookId, timestamp and rawSignatures
+     */
+    private verifyHeaders;
+    /**
+     * Signs the content with the secret
+     * @param content
+     * @returns `string`
+     */
+    private sign;
+    /**
+     * Verifies that the timestamp is not too old or in the future
+     */
+    private verifyTimestamp;
+    /**
+     * Ensures that the event is a known event type
+     * or throws and prompts the user to upgrade to a higher version of @liveblocks/node
+     */
+    private verifyWebhookEventType;
+}
+declare type WebhookRequest = {
+    /**
+     * Headers of the request
+     * @example
+     * {
+     *  "webhook-id": "123",
+     *  "webhook-timestamp": "1614588800000",
+     *  "webhook-signature": "v1,bm9ldHUjKzFob2VudXRob2VodWUzMjRvdWVvdW9ldQo= v2,MzJsNDk4MzI0K2VvdSMjMTEjQEBAQDEyMzMzMzEyMwo="
+     * }
+     */
+    headers: IncomingHttpHeaders;
+    /**
+     * Raw body of the request, do not parse it
+     * @example '{"type":"storageUpdated","data":{"roomId":"my-room-id","appId":"my-app-id","updatedAt":"2021-03-01T12:00:00.000Z"}}'
+     */
+    rawBody: string;
+};
+declare type WebhookEvent = StorageUpdatedEvent | UserEnteredEvent | UserLeftEvent | RoomCreatedEvent | RoomDeletedEvent;
+declare type StorageUpdatedEvent = {
+    type: "storageUpdated";
+    data: {
+        roomId: string;
+        appId: string;
+        /**
+         * ISO 8601 datestring
+         * @example "2021-03-01T12:00:00.000Z"
+         */
+        updatedAt: string;
+    };
+};
+declare type UserEnteredEvent = {
+    type: "userEntered";
+    data: {
+        appId: string;
+        roomId: string;
+        connectionId: number;
+        userId: string | null;
+        userInfo: Record<string, unknown> | null;
+        /**
+         * ISO 8601 datestring
+         * @example "2021-03-01T12:00:00.000Z"
+         * @description The time when the user entered the room.
+         */
+        enteredAt: string;
+        numActiveUsers: number;
+    };
+};
+declare type UserLeftEvent = {
+    type: "userLeft";
+    data: {
+        appId: string;
+        roomId: string;
+        connectionId: number;
+        userId: string | null;
+        userInfo: Record<string, unknown> | null;
+        /**
+         * ISO 8601 datestring
+         * @example "2021-03-01T12:00:00.000Z"
+         * @description The time when the user left the room.
+         */
+        leftAt: string;
+        numActiveUsers: number;
+    };
+};
+declare type RoomCreatedEvent = {
+    type: "roomCreated";
+    data: {
+        appId: string;
+        roomId: string;
+        /**
+         * ISO 8601 datestring
+         * @example "2021-03-01T12:00:00.000Z"
+         */
+        createdAt: string;
+    };
+};
+declare type RoomDeletedEvent = {
+    type: "roomDeleted";
+    data: {
+        appId: string;
+        roomId: string;
+        /**
+         * ISO 8601 datestring
+         * @example "2021-03-01T12:00:00.000Z"
+         */
+        deletedAt: string;
+    };
+};
+
+export { Liveblocks, LiveblocksOptions, StorageUpdatedEvent, UserEnteredEvent, UserLeftEvent, WebhookEvent, WebhookHandler, WebhookRequest, authorize };

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 import { IncomingHttpHeaders } from 'http';
 
+/**
+ * TODO Officially mark as DEPRECATED, point to migration guide.
+ */
 declare type AuthorizeOptions = {
     /**
      * The secret API key for your Liveblocks account. You can find it on
@@ -46,12 +49,17 @@ declare type AuthorizeOptions = {
      */
     groupIds?: string[];
 };
+/**
+ * TODO Officially mark as DEPRECATED, point to migration guide.
+ */
 declare type AuthorizeResponse = {
     status: number;
     body: string;
     error?: Error;
 };
 /**
+ * TODO Officially mark as DEPRECATED, point to migration guide.
+ *
  * Tells Liveblocks that a user should be allowed access to a room, which user
  * this session is for, and what metadata to associate with the user (like
  * name, avatar, etc.)
@@ -76,6 +84,136 @@ declare type AuthorizeResponse = {
  */
 declare function authorize(options: AuthorizeOptions): Promise<AuthorizeResponse>;
 
+declare const ALL_PERMISSIONS: readonly ["room:write", "room:read", "room:presence:write", "comments:write", "comments:read"];
+declare type Permission = (typeof ALL_PERMISSIONS)[number];
+/**
+ * Class to help you construct the exact permission set to grant a user, used
+ * when making `.authorizeUser()` calls.
+ *
+ * Usage:
+ *
+ *    const session = liveblocks.prepareSession();
+ *    session.allow(roomId, permissions)  // or...
+ *
+ * For the `permissions` argument, you can pass a list of specific permissions,
+ * or use one of our presets:
+ *
+ *    session.allow('my-room', session.FULL_ACCESS)  // Read + write access to room storage and comments
+ *    session.allow('my-room', session.READ_ACCESS)  // Read-only access to room storage and comments
+ *
+ * Rooms can be specified with a prefix match, if the name ends in an asterisk.
+ * In that case, access is granted to *all* rooms that start with that prefix:
+ *
+ *    // Read + write access to *all* rooms that start with "abc:"
+ *    session.allow('abc:*', session.FULL_ACCESS)
+ *
+ * You can define at most 10 room IDs (or patterns) in a single token,
+ * otherwise the token would become too large and unwieldy.
+ *
+ * All permissions granted are additive. You cannot "remove" permissions once
+ * you grant them. For example:
+ *
+ *    session
+ *      .allow('abc:*',   session.FULL_ACCESS)
+ *      .allow('abc:123', session.READ_ACCESS)
+ *
+ * Here, room `abc:123` would have full access. The second .allow() call only
+ * _adds_ read permissions, but that has no effect since full access
+ * permissions were already added to the set.
+ */
+declare class Session {
+    readonly FULL_ACCESS: readonly ["room:write", "comments:write"];
+    readonly READ_ACCESS: readonly ["room:read", "room:presence:write", "comments:read"];
+    allow(roomIdOrPattern: string, newPerms: readonly Permission[]): this;
+    /**
+     * Call this to authorize the session to access Liveblocks. Note that this
+     * will return a Liveblocks "access token". Anyone that obtains such access
+     * token will have access to the allowed resources.
+     */
+    authorize(): Promise<AuthResponse>;
+}
+
+declare type LiveblocksOptions = {
+    /**
+     * The Liveblocks secret key. Must start with "sk_".
+     * Get it from https://liveblocks.io/dashboard/apikeys
+     */
+    secret: string;
+};
+declare type CreateSessionOptions = {
+    userInfo: unknown;
+};
+declare type AuthResponse = {
+    status: number;
+    body: string;
+    error?: Error;
+};
+declare type Identity = {
+    userId: string;
+    groupIds: string[];
+};
+/**
+ * Interact with the Liveblocks API from your Node.js backend.
+ */
+declare class Liveblocks {
+    /**
+     * Interact with the Liveblocks API from your Node.js backend.
+     */
+    constructor(options: LiveblocksOptions);
+    /**
+     * Prepares a new session to authorize a user to access Liveblocks.
+     *
+     * IMPORTANT:
+     * Always make sure that you trust the user making the request to your
+     * backend before calling .prepareSession()!
+     *
+     * @param userId Tell Liveblocks the user ID of the user to authorize. Must
+     * uniquely identify the user account in your system. The uniqueness of this
+     * value will determine how many MAUs will be counted/billed.
+     *
+     * @param options.userInfo Custom metadata to attach to this user. Data you
+     * add here will be visible to all other clients in the room, through the
+     * `other.info` property.
+     *
+     */
+    prepareSession(userId: string, options?: CreateSessionOptions): Session;
+    /**
+     * Call this to authenticate the user as an actor you want to allow to use
+     * Liveblocks.
+     *
+     * You should use this method only if you want to manage your permissions
+     * through the Liveblocks Permissions API. This method is more complicated to
+     * set up, but allows for finer-grained specification of permissions.
+     *
+     * Calling `.identifyUser()` only lets you securely identify a user (and what
+     * groups they belong to). What permissions this user will end up having is
+     * determined by whatever permissions you assign the user/group in your
+     * Liveblocks account, through the Permissions API:
+     * https://liveblocks.io/docs/rooms/permissions
+     *
+     * IMPORTANT:
+     * Always verify that you trust the user making the request before calling
+     * .identifyUser()!
+     *
+     * @param identity Tell Liveblocks the user ID of the user to authenticate.
+     * Must uniquely identify the user account in your system. The uniqueness of
+     * this value will determine how many MAUs will be counted/billed.
+     *
+     * If you also want to assign which groups this user belongs to, use the
+     * object form and specify the `groupIds` property. Those `groupIds` should
+     * match the groupIds you assigned permissions to via the Liveblocks
+     * Permissions API, see
+     * https://liveblocks.io/docs/rooms/permissions#permissions-levels-groups-accesses-example
+     *
+     * @param options.userInfo Custom metadata to attach to this user. Data you
+     * add here will be visible to all other clients in the room, through the
+     * `other.info` property.
+     */
+    identifyUser(identity: string | Identity, options?: {
+        userInfo: unknown;
+    }): Promise<AuthResponse>;
+}
+
 declare class WebhookHandler {
     private secretBuffer;
     private static secretPrefix;
@@ -198,4 +336,4 @@ declare type RoomDeletedEvent = {
     };
 };
 
-export { StorageUpdatedEvent, UserEnteredEvent, UserLeftEvent, WebhookEvent, WebhookHandler, WebhookRequest, authorize };
+export { Liveblocks, LiveblocksOptions, StorageUpdatedEvent, UserEnteredEvent, UserLeftEvent, WebhookEvent, WebhookHandler, WebhookRequest, authorize };