@knocklabs/node 0.6.19 → 1.1.0

package/src/lib/tokenSigner.ts

@@ -0,0 +1,170 @@
+/**
+ * Token signing functionality for Knock authentication
+ */
+
+import * as crypto from 'crypto';
+import type { TokenEntity, TokenGrant, TokenGrantOptions } from './userTokens';
+
+// Default hostname for Knock API
+const DEFAULT_HOSTNAME = 'https://api.knock.app';
+
+/**
+ * Options for signing a user token
+ */
+export interface SignUserTokenOptions {
+  /**
+   * The signing key to use (in PEM or base-64 encoded format)
+   * If not provided, it will try to use process.env.KNOCK_SIGNING_KEY
+   */
+  signingKey?: string | undefined;
+
+  /**
+   * How long the token should be valid for in seconds
+   * @default 3600 (1 hour)
+   */
+  expiresInSeconds?: number | undefined;
+
+  /**
+   * Grants to include in the token
+   */
+  grants?: TokenGrant[] | undefined;
+}
+
+/**
+ * Prepare the signing key for use
+ */
+function prepareSigningKey(key?: string): string {
+  const maybeSigningKey = key ?? process.env['KNOCK_SIGNING_KEY'];
+  if (!maybeSigningKey)
+    throw new Error(
+      'No signing key provided. Set KNOCK_SIGNING_KEY environment variable or pass signingKey option.',
+    );
+
+  // If it's already in PEM format
+  if (maybeSigningKey.startsWith('-----BEGIN')) return maybeSigningKey;
+
+  // LS0tLS1CRUdJTi is the base64 encoded version of "-----BEGIN"
+  if (maybeSigningKey.startsWith('LS0tLS1CRUdJTi'))
+    return Buffer.from(maybeSigningKey, 'base64').toString('utf-8');
+
+  throw new Error('Invalid signing key format. Must be PEM or base64 encoded PEM.');
+}
+
+/**
+ * Prepare the token entity URI
+ */
+function prepareTokenEntityUri(entity: TokenEntity): string {
+  switch (entity.type) {
+    case 'user':
+      return `${DEFAULT_HOSTNAME}/v1/users/${entity.id}`;
+    case 'tenant':
+      return `${DEFAULT_HOSTNAME}/v1/objects/$tenants/${entity.id}`;
+    case 'object':
+      return `${DEFAULT_HOSTNAME}/v1/objects/${entity.collection}/${entity.id}`;
+  }
+}
+
+/**
+ * Create and sign a JWT using Node.js crypto
+ */
+function createJWT(header: object, payload: object, privateKey: string): string {
+  // Base64Url encode the header
+  const headerBase64 = Buffer.from(JSON.stringify(header))
+    .toString('base64')
+    .replace(/=/g, '')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_');
+
+  // Base64Url encode the payload
+  const payloadBase64 = Buffer.from(JSON.stringify(payload))
+    .toString('base64')
+    .replace(/=/g, '')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_');
+
+  // Create the content to sign
+  const signatureContent = `${headerBase64}.${payloadBase64}`;
+
+  // Sign the content
+  const signer = crypto.createSign('RSA-SHA256');
+  signer.update(signatureContent);
+
+  const signature = signer
+    .sign(privateKey, 'base64')
+    .replace(/=/g, '')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_');
+
+  // Combine to create the JWT
+  return `${signatureContent}.${signature}`;
+}
+
+/**
+ * Prepare user token grants
+ */
+export function maybePrepareUserTokenGrants(
+  grants: TokenGrant[] | undefined,
+): Record<string, TokenGrant['grants']> | undefined {
+  if (!grants) return undefined;
+
+  // Given a list of token grants, flattens them into a single object
+  // like: { "entity": { "slack/channels_read": [] } }
+  return grants.reduce<Record<string, TokenGrant['grants']>>((acc, grant) => {
+    if (acc[grant.entity]) {
+      const currentGrants = acc[grant.entity];
+      return { ...acc, [grant.entity]: { ...currentGrants, ...grant.grants } };
+    } else {
+      return { ...acc, [grant.entity]: grant.grants };
+    }
+  }, {});
+}
+
+/**
+ * Helper function to build user token grants to pass to the `signUserToken` method.
+ *
+ * @param entity {TokenEntity} The type of entity to build a grant for
+ * @param grants {TokenGrantOptions} A list of grants to give to the entity for the user
+ *
+ * @returns {TokenGrant} A single token grant that can be passed to the signUserToken function
+ */
+export function buildUserTokenGrant(entity: TokenEntity, grants: TokenGrantOptions): TokenGrant {
+  return {
+    entity: prepareTokenEntityUri(entity),
+    grants: grants.reduce((acc, grant) => ({ ...acc, [grant]: [] }), {}),
+  };
+}
+
+/**
+ * Generate JWT for authenticating client-side requests (e.g. in-app feeds)
+ * For more information, visit https://docs.knock.app/in-app-ui/security-and-authentication#authentication-with-enhanced-security-enabled
+ *
+ * @param userId {string} The ID of the user that needs a token, e.g. the user viewing an in-app feed.
+ * @param options Optionally specify the signing key to use (in PEM or base-64 encoded format), and how long the token should be valid for in seconds
+ * @returns {Promise<string>} A JWT token that can be used to authenticate requests to the Knock API (e.g. by passing into the <KnockFeedProvider /> component)
+ */
+export async function signUserToken(userId: string, options?: SignUserTokenOptions): Promise<string> {
+  const signingKey = prepareSigningKey(options?.signingKey);
+
+  // JWT NumericDates specified in seconds
+  const currentTime = Math.floor(Date.now() / 1000);
+
+  // Default to 1 hour from now
+  const expireInSeconds = options?.expiresInSeconds ?? 60 * 60;
+
+  // Create JWT header
+  const header = {
+    alg: 'RS256',
+    typ: 'JWT',
+  };
+
+  // Create JWT payload
+  const payload = {
+    sub: userId,
+    grants: maybePrepareUserTokenGrants(options?.grants),
+    iat: currentTime,
+    exp: currentTime + expireInSeconds,
+  };
+
+  // Create and sign the JWT
+  return createJWT(header, payload, signingKey);
+}

package/src/lib/userTokens.ts

@@ -0,0 +1,38 @@
+/**
+ * User token signing functionality for Knock authentication
+ */
+
+export enum Grants {
+  SlackChannelsRead = 'slack/channels_read',
+  MsTeamsChannelsRead = 'ms_teams/channels_read',
+  ChannelDataRead = 'channel_data/read',
+  ChannelDataWrite = 'channel_data/write',
+  UserFeedRead = 'user/feed_read',
+}
+
+export type TokenGrantOptions = Grants[];
+
+export type TokenEntity = TenantTokenEntity | UserTokenEntity | ObjectTokenEntity;
+
+export interface TenantTokenEntity {
+  type: 'tenant';
+  id: string;
+  collection?: never;
+}
+
+export interface ObjectTokenEntity {
+  type: 'object';
+  id: string;
+  collection: string;
+}
+
+export interface UserTokenEntity {
+  type: 'user';
+  id: string;
+  collection?: never;
+}
+
+export type TokenGrant = {
+  entity: string;
+  grants: Partial<Record<Grants, []>>;
+};

package/src/pagination.ts

@@ -0,0 +1,2 @@
+/** @deprecated Import from ./core/pagination instead */
+export * from './core/pagination';

package/src/resource.ts

@@ -0,0 +1,2 @@
+/** @deprecated Import from ./core/resource instead */
+export * from './core/resource';

package/src/resources/audiences.ts

@@ -0,0 +1,200 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import * as SharedAPI from './shared';
+import * as UsersAPI from './users/users';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+export class Audiences extends APIResource {
+  /**
+   * Adds one or more members to the specified audience.
+   *
+   * @example
+   * ```ts
+   * const response = await client.audiences.addMembers('key', {
+   *   members: [
+   *     {
+   *       tenant: 'ingen_isla_nublar',
+   *       user: { id: 'dr_sattler' },
+   *     },
+   *   ],
+   * });
+   * ```
+   */
+  addMembers(key: string, body: AudienceAddMembersParams, options?: RequestOptions): APIPromise<string> {
+    return this._client.post(path`/v1/audiences/${key}/members`, { body, ...options });
+  }
+
+  /**
+   * Returns a paginated list of members for the specified audience.
+   *
+   * @example
+   * ```ts
+   * const response = await client.audiences.listMembers('key');
+   * ```
+   */
+  listMembers(key: string, options?: RequestOptions): APIPromise<AudienceListMembersResponse> {
+    return this._client.get(path`/v1/audiences/${key}/members`, options);
+  }
+
+  /**
+   * Removes one or more members from the specified audience.
+   *
+   * @example
+   * ```ts
+   * const response = await client.audiences.removeMembers(
+   *   'key',
+   *   { members: [{ user: {} }] },
+   * );
+   * ```
+   */
+  removeMembers(
+    key: string,
+    body: AudienceRemoveMembersParams,
+    options?: RequestOptions,
+  ): APIPromise<string> {
+    return this._client.delete(path`/v1/audiences/${key}/members`, { body, ...options });
+  }
+}
+
+/**
+ * An audience member.
+ */
+export interface AudienceMember {
+  /**
+   * The typename of the schema.
+   */
+  __typename: string;
+
+  /**
+   * Timestamp when the resource was created.
+   */
+  added_at: string;
+
+  /**
+   * A [User](/concepts/users) represents an individual in your system who can
+   * receive notifications through Knock. Users are the most common recipients of
+   * notifications and are always referenced by your internal identifier.
+   */
+  user: UsersAPI.User;
+
+  /**
+   * The ID for the user that you set when identifying them in Knock.
+   */
+  user_id: string;
+
+  /**
+   * The unique identifier for the tenant.
+   */
+  tenant?: string | null;
+}
+
+/**
+ * A `204 No Content` response.
+ */
+export type AudienceAddMembersResponse = string;
+
+/**
+ * A paginated list of audience members.
+ */
+export interface AudienceListMembersResponse {
+  /**
+   * A list of audience members.
+   */
+  entries: Array<AudienceMember>;
+
+  /**
+   * Pagination information for a list of resources.
+   */
+  page_info: SharedAPI.PageInfo;
+}
+
+/**
+ * A `204 No Content` response.
+ */
+export type AudienceRemoveMembersResponse = string;
+
+export interface AudienceAddMembersParams {
+  /**
+   * A list of audience members to add.
+   */
+  members: Array<AudienceAddMembersParams.Member>;
+}
+
+export namespace AudienceAddMembersParams {
+  /**
+   * An audience member.
+   */
+  export interface Member {
+    /**
+     * An object containing the user's ID.
+     */
+    user: Member.User;
+
+    /**
+     * The unique identifier for the tenant.
+     */
+    tenant?: string | null;
+  }
+
+  export namespace Member {
+    /**
+     * An object containing the user's ID.
+     */
+    export interface User {
+      /**
+       * The ID for the user that you set when identifying them in Knock.
+       */
+      id?: string;
+    }
+  }
+}
+
+export interface AudienceRemoveMembersParams {
+  /**
+   * A list of audience members to remove.
+   */
+  members: Array<AudienceRemoveMembersParams.Member>;
+}
+
+export namespace AudienceRemoveMembersParams {
+  /**
+   * An audience member.
+   */
+  export interface Member {
+    /**
+     * An object containing the user's ID.
+     */
+    user: Member.User;
+
+    /**
+     * The unique identifier for the tenant.
+     */
+    tenant?: string | null;
+  }
+
+  export namespace Member {
+    /**
+     * An object containing the user's ID.
+     */
+    export interface User {
+      /**
+       * The ID for the user that you set when identifying them in Knock.
+       */
+      id?: string;
+    }
+  }
+}
+
+export declare namespace Audiences {
+  export {
+    type AudienceMember as AudienceMember,
+    type AudienceAddMembersResponse as AudienceAddMembersResponse,
+    type AudienceListMembersResponse as AudienceListMembersResponse,
+    type AudienceRemoveMembersResponse as AudienceRemoveMembersResponse,
+    type AudienceAddMembersParams as AudienceAddMembersParams,
+    type AudienceRemoveMembersParams as AudienceRemoveMembersParams,
+  };
+}

package/src/resources/bulk-operations.ts

@@ -0,0 +1,120 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+export class BulkOperations extends APIResource {
+  /**
+   * Retrieves a bulk operation (if it exists) and displays the current state of it.
+   *
+   * @example
+   * ```ts
+   * const bulkOperation = await client.bulkOperations.get(
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   * );
+   * ```
+   */
+  get(id: string, options?: RequestOptions): APIPromise<BulkOperation> {
+    return this._client.get(path`/v1/bulk_operations/${id}`, options);
+  }
+}
+
+/**
+ * A bulk operation entity.
+ */
+export interface BulkOperation {
+  /**
+   * Unique identifier for the bulk operation.
+   */
+  id: string;
+
+  /**
+   * The typename of the schema.
+   */
+  __typename: string;
+
+  /**
+   * The estimated total number of rows to process.
+   */
+  estimated_total_rows: number;
+
+  /**
+   * Timestamp when the resource was created.
+   */
+  inserted_at: string;
+
+  /**
+   * The name of the bulk operation.
+   */
+  name: string;
+
+  /**
+   * The number of rows processed so far.
+   */
+  processed_rows: number;
+
+  /**
+   * The status of the bulk operation.
+   */
+  status: 'queued' | 'processing' | 'completed' | 'failed';
+
+  /**
+   * The number of successful operations.
+   */
+  success_count: number;
+
+  /**
+   * The timestamp when the resource was last updated.
+   */
+  updated_at: string;
+
+  /**
+   * Timestamp when the bulk operation was completed.
+   */
+  completed_at?: string | null;
+
+  /**
+   * The number of failed operations.
+   */
+  error_count?: number;
+
+  /**
+   * A list of items that failed to be processed.
+   */
+  error_items?: Array<BulkOperation.ErrorItem>;
+
+  /**
+   * Timestamp when the bulk operation failed.
+   */
+  failed_at?: string | null;
+
+  /**
+   * The URI to the bulk operation's progress.
+   */
+  progress_path?: string;
+
+  /**
+   * Timestamp when the bulk operation was started.
+   */
+  started_at?: string | null;
+}
+
+export namespace BulkOperation {
+  export interface ErrorItem {
+    /**
+     * Unique identifier for the object.
+     */
+    id: string;
+
+    /**
+     * The collection this object belongs to.
+     */
+    collection?: string | null;
+  }
+}
+
+export declare namespace BulkOperations {
+  export { type BulkOperation as BulkOperation };
+}

package/src/resources/channels/bulk.ts

@@ -0,0 +1,128 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as BulkOperationsAPI from '../bulk-operations';
+import { APIPromise } from '../../core/api-promise';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+export class Bulk extends APIResource {
+  /**
+   * Bulk update the status of messages for a specific channel. The channel is
+   * specified by the `channel_id` parameter. The action to perform is specified by
+   * the `action` parameter, where the action is a status change action (e.g.
+   * `archive`, `unarchive`).
+   *
+   * @example
+   * ```ts
+   * const bulkOperation =
+   *   await client.channels.bulk.updateMessageStatus(
+   *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *     'seen',
+   *     {
+   *       archived: 'include',
+   *       delivery_status: 'delivered',
+   *       engagement_status: 'seen',
+   *       has_tenant: true,
+   *       newer_than: '2024-01-01T00:00:00Z',
+   *       older_than: '2024-01-01T00:00:00Z',
+   *       recipient_ids: ['recipient1', 'recipient2'],
+   *       tenants: ['tenant1', 'tenant2'],
+   *       trigger_data: '{"key":"value"}',
+   *       workflows: ['workflow1', 'workflow2'],
+   *     },
+   *   );
+   * ```
+   */
+  updateMessageStatus(
+    channelID: string,
+    action:
+      | 'seen'
+      | 'unseen'
+      | 'read'
+      | 'unread'
+      | 'archived'
+      | 'unarchived'
+      | 'interacted'
+      | 'archive'
+      | 'unarchive'
+      | 'delete',
+    body: BulkUpdateMessageStatusParams,
+    options?: RequestOptions,
+  ): APIPromise<BulkOperationsAPI.BulkOperation> {
+    return this._client.post(path`/v1/channels/${channelID}/messages/bulk/${action}`, { body, ...options });
+  }
+}
+
+export interface BulkUpdateMessageStatusParams {
+  /**
+   * Limits the results to messages with the given archived status.
+   */
+  archived?: 'exclude' | 'include' | 'only';
+
+  /**
+   * Limits the results to messages with the given delivery status.
+   */
+  delivery_status?:
+    | 'queued'
+    | 'sent'
+    | 'delivered'
+    | 'delivery_attempted'
+    | 'undelivered'
+    | 'not_sent'
+    | 'bounced';
+
+  /**
+   * Limits the results to messages with the given engagement status.
+   */
+  engagement_status?:
+    | 'seen'
+    | 'unseen'
+    | 'read'
+    | 'unread'
+    | 'archived'
+    | 'unarchived'
+    | 'link_clicked'
+    | 'interacted';
+
+  /**
+   * Limits the results to messages that have a tenant or not.
+   */
+  has_tenant?: boolean;
+
+  /**
+   * Limits the results to messages inserted after the given date.
+   */
+  newer_than?: string;
+
+  /**
+   * Limits the results to messages inserted before the given date.
+   */
+  older_than?: string;
+
+  /**
+   * Limits the results to messages with the given recipient IDs.
+   */
+  recipient_ids?: Array<string>;
+
+  /**
+   * Limits the results to messages with the given tenant IDs.
+   */
+  tenants?: Array<string>;
+
+  /**
+   * Limits the results to only messages that were generated with the given data. See
+   * [trigger data filtering](/api-reference/overview/trigger-data-filtering) for
+   * more information.
+   */
+  trigger_data?: string;
+
+  /**
+   * Limits the results to messages with the given workflow keys.
+   */
+  workflows?: Array<string>;
+}
+
+export declare namespace Bulk {
+  export { type BulkUpdateMessageStatusParams as BulkUpdateMessageStatusParams };
+}

package/src/resources/channels/channels.ts

@@ -0,0 +1,15 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as BulkAPI from './bulk';
+import { Bulk, BulkUpdateMessageStatusParams } from './bulk';
+
+export class Channels extends APIResource {
+  bulk: BulkAPI.Bulk = new BulkAPI.Bulk(this._client);
+}
+
+Channels.Bulk = Bulk;
+
+export declare namespace Channels {
+  export { Bulk as Bulk, type BulkUpdateMessageStatusParams as BulkUpdateMessageStatusParams };
+}

package/src/resources/channels/index.ts

@@ -0,0 +1,4 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export { Bulk, type BulkUpdateMessageStatusParams } from './bulk';
+export { Channels } from './channels';

package/src/resources/channels.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './channels/index';