@knocklabs/node 0.6.19 → 1.0.0

package/src/internal/utils/path.ts

@@ -0,0 +1,63 @@
+import { KnockError } from '../../core/error';
+
+/**
+ * Percent-encode everything that isn't safe to have in a path without encoding safe chars.
+ *
+ * Taken from https://datatracker.ietf.org/doc/html/rfc3986#section-3.3:
+ * > unreserved  = ALPHA / DIGIT / "-" / "." / "_" / "~"
+ * > sub-delims  = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "="
+ * > pchar       = unreserved / pct-encoded / sub-delims / ":" / "@"
+ */
+export function encodeURIPath(str: string) {
+  return str.replace(/[^A-Za-z0-9\-._~!$&'()*+,;=:@]+/g, encodeURIComponent);
+}
+
+export const createPathTagFunction = (pathEncoder = encodeURIPath) =>
+  function path(statics: readonly string[], ...params: readonly unknown[]): string {
+    // If there are no params, no processing is needed.
+    if (statics.length === 1) return statics[0]!;
+
+    let postPath = false;
+    const path = statics.reduce((previousValue, currentValue, index) => {
+      if (/[?#]/.test(currentValue)) {
+        postPath = true;
+      }
+      return (
+        previousValue +
+        currentValue +
+        (index === params.length ? '' : (postPath ? encodeURIComponent : pathEncoder)(String(params[index])))
+      );
+    }, '');
+
+    const pathOnly = path.split(/[?#]/, 1)[0]!;
+    const invalidSegments = [];
+    const invalidSegmentPattern = /(?<=^|\/)(?:\.|%2e){1,2}(?=\/|$)/gi;
+    let match;
+
+    // Find all invalid segments
+    while ((match = invalidSegmentPattern.exec(pathOnly)) !== null) {
+      invalidSegments.push({
+        start: match.index,
+        length: match[0].length,
+      });
+    }
+
+    if (invalidSegments.length > 0) {
+      let lastEnd = 0;
+      const underline = invalidSegments.reduce((acc, segment) => {
+        const spaces = ' '.repeat(segment.start - lastEnd);
+        const arrows = '^'.repeat(segment.length);
+        lastEnd = segment.start + segment.length;
+        return acc + spaces + arrows;
+      }, '');
+
+      throw new KnockError(`Path parameters result in path with invalid segments:\n${path}\n${underline}`);
+    }
+
+    return path;
+  };
+
+/**
+ * URI-encodes path params and ensures no unsafe /./ or /../ path segments are introduced.
+ */
+export const path = createPathTagFunction(encodeURIPath);

package/src/internal/utils/sleep.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));

package/src/internal/utils/uuid.ts

@@ -0,0 +1,19 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { getCrypto } from '../shims/crypto';
+
+/**
+ * https://stackoverflow.com/a/2117523
+ */
+export let uuid4 = function () {
+  const crypto = getCrypto();
+  if (crypto?.randomUUID) {
+    uuid4 = crypto.randomUUID.bind(crypto);
+    return crypto.randomUUID();
+  }
+  const u8 = new Uint8Array(1);
+  const randomByte = crypto ? () => crypto.getRandomValues(u8)[0]! : () => (Math.random() * 0xff) & 0xff;
+  return '10000000-1000-4000-8000-100000000000'.replace(/[018]/g, (c) =>
+    (+c ^ (randomByte() & (15 >> (+c / 4)))).toString(16),
+  );
+};

package/src/internal/utils/values.ts

@@ -0,0 +1,102 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { KnockError } from '../../core/error';
+
+// https://url.spec.whatwg.org/#url-scheme-string
+const startsWithSchemeRegexp = /^[a-z][a-z0-9+.-]*:/i;
+
+export const isAbsoluteURL = (url: string): boolean => {
+  return startsWithSchemeRegexp.test(url);
+};
+
+/** Returns an object if the given value isn't an object, otherwise returns as-is */
+export function maybeObj(x: unknown): object {
+  if (typeof x !== 'object') {
+    return {};
+  }
+
+  return x ?? {};
+}
+
+// https://stackoverflow.com/a/34491287
+export function isEmptyObj(obj: Object | null | undefined): boolean {
+  if (!obj) return true;
+  for (const _k in obj) return false;
+  return true;
+}
+
+// https://eslint.org/docs/latest/rules/no-prototype-builtins
+export function hasOwn<T extends object = object>(obj: T, key: PropertyKey): key is keyof T {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+export function isObj(obj: unknown): obj is Record<string, unknown> {
+  return obj != null && typeof obj === 'object' && !Array.isArray(obj);
+}
+
+export const ensurePresent = <T>(value: T | null | undefined): T => {
+  if (value == null) {
+    throw new KnockError(`Expected a value to be given but received ${value} instead.`);
+  }
+
+  return value;
+};
+
+export const validatePositiveInteger = (name: string, n: unknown): number => {
+  if (typeof n !== 'number' || !Number.isInteger(n)) {
+    throw new KnockError(`${name} must be an integer`);
+  }
+  if (n < 0) {
+    throw new KnockError(`${name} must be a positive integer`);
+  }
+  return n;
+};
+
+export const coerceInteger = (value: unknown): number => {
+  if (typeof value === 'number') return Math.round(value);
+  if (typeof value === 'string') return parseInt(value, 10);
+
+  throw new KnockError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
+};
+
+export const coerceFloat = (value: unknown): number => {
+  if (typeof value === 'number') return value;
+  if (typeof value === 'string') return parseFloat(value);
+
+  throw new KnockError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
+};
+
+export const coerceBoolean = (value: unknown): boolean => {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'string') return value === 'true';
+  return Boolean(value);
+};
+
+export const maybeCoerceInteger = (value: unknown): number | undefined => {
+  if (value === undefined) {
+    return undefined;
+  }
+  return coerceInteger(value);
+};
+
+export const maybeCoerceFloat = (value: unknown): number | undefined => {
+  if (value === undefined) {
+    return undefined;
+  }
+  return coerceFloat(value);
+};
+
+export const maybeCoerceBoolean = (value: unknown): boolean | undefined => {
+  if (value === undefined) {
+    return undefined;
+  }
+  return coerceBoolean(value);
+};
+
+export const safeJSON = (text: string) => {
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    return undefined;
+  }
+};

package/src/internal/utils.ts

@@ -0,0 +1,8 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './utils/values';
+export * from './utils/base64';
+export * from './utils/env';
+export * from './utils/log';
+export * from './utils/uuid';
+export * from './utils/sleep';

package/src/lib/.keep

@@ -0,0 +1,4 @@
+File generated from our OpenAPI spec by Stainless.
+
+This directory can be used to store custom files to expand the SDK.
+It is ignored by Stainless code generation and its content (other than this keep file) won't be touched.

package/src/lib/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Exports for Knock custom functionality
+ */
+
+export * from './userTokens';
+export * from './tokenSigner';

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,163 @@
+// 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.
+   */
+  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.
+   */
+  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.
+   */
+  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 {
+    user: Member.User;
+
+    /**
+     * The unique identifier for the tenant.
+     */
+    tenant?: string | null;
+  }
+
+  export namespace Member {
+    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 {
+    user: Member.User;
+
+    /**
+     * The unique identifier for the tenant.
+     */
+    tenant?: string | null;
+  }
+
+  export namespace Member {
+    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,
+  };
+}