@knocklabs/node 0.4.14 → 0.4.16

package/README.md

@@ -16,13 +16,16 @@ npm install @knocklabs/node
 
 To use the library you must provide a secret API key, provided in the Knock dashboard.
 
-You can set it as an environment variable:
+If you are using [enhanced security mode](https://docs.knock.app/client-integration/authenticating-users) you will also need to provide your signing key.
+
+You can set both as environment variables:
 
 ```bash
 KNOCK_API_KEY="sk_12345"
+KNOCK_SIGNING_KEY="S25vY2sga25vY2sh..."
 ```
 
-Or, you can set it before your application starts:
+You can also pass the Knock API key in the constructor. The signing key is passed separately to the `signUserToken` method (see below):
 
 ```javascript
 const { Knock } = require("@knocklabs/node");
@@ -135,27 +138,24 @@ await knockClient.users.getChannelData("jhammond", KNOCK_APNS_CHANNEL_ID);
 
 ### Signing JWTs
 
-You can use the `jsonwebtoken` package to [sign JWTs easily](https://www.npmjs.com/package/jsonwebtoken#jwtsignpayload-secretorprivatekey-options-callback).
-You will need to generate an environment specific signing key, which you can find in the Knock dashboard.
+When using [enhanced security mode](https://docs.knock.app/client-integration/authenticating-users) (recommended in production), you will need to sign JWTs server-side to authenticate your users.
 
-If you're using a signing token you will need to pass this to your client to perform authentication.
-You can read more about [client-side authentication here](https://docs.knock.app/client-integration/authenticating-users).
+You will need to generate an environment specific signing key in the Knock dashboard under "API Keys", and then enable enhanced security mode for your environment.
 
 ```javascript
-const jwt = require("jsonwebtoken");
-
-const currentTime = Math.floor(Date.now() / 1000);
-
-const token = jwt.sign(
-  {
-    // The user id to sign this key for
-    sub: "jhammond",
-    // When the token was issued
-    iat: currentTime,
-    // When the token expires (1 hour)
-    exp: currentTime + 60 * 60,
-  },
-  process.env.KNOCK_SIGNING_KEY,
-  { algorithm: "RS256" },
-);
+const { Knock } = require("@knocklabs/node");
+
+// When signing user tokens, you do not need to instantiate a Knock client.
+
+// jhammond is the user id for which to sign this token
+const token = Knock.signUserToken("jhammond", {
+  // The signing key from the Knock Dashboard in base-64 or PEM-encoded format.
+  // If not provided, the key will be read from the KNOCK_SIGNING_KEY environment variable.
+  signingKey: "S25vY2sga25vY2sh...",
+  // Optional: How long the token should be valid for, in seconds (default 1 hour)
+  // For long-lived connections, you will need to refresh the token before it expires.
+  expiresIn: 60 * 60,
+});
+
+// This token can now be safely passed to your client e.g. in a cookie or API response.
 ```

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@knocklabs/node",
-    "version": "0.4.14",
+    "version": "0.4.16",
     "description": "Library for interacting with the Knock API",
     "homepage": "https://github.com/knocklabs/knock-node",
     "author": "@knocklabs",
@@ -32,6 +32,7 @@
     },
     "devDependencies": {
         "@types/jest": "26.0.23",
+        "@types/jsonwebtoken": "^9.0.1",
         "@types/node": "^15.0.1",
         "@types/pluralize": "0.0.29",
         "axios-mock-adapter": "1.19.0",
@@ -43,6 +44,7 @@
         "typescript": "4.2.4"
     },
     "dependencies": {
-        "axios": "^0.21.1"
+        "axios": "^0.21.1",
+        "jsonwebtoken": "^9.0.0"
     }
 }

package/dist/src/common/exceptions.d.ts

@@ -4,6 +4,11 @@ export declare class NoApiKeyProvidedException extends Error {
     readonly name: string;
     readonly message: string;
 }
+export declare class NoSigningKeyProvidedException extends Error {
+    readonly status: number;
+    readonly name: string;
+    readonly message: string;
+}
 export declare class GenericServerException implements HttpException {
     readonly status: number;
     readonly requestID: string;

package/dist/src/common/exceptions.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BadRequestException = exports.UnprocessableEntityException = exports.NotFoundException = exports.UnauthorizedException = exports.GenericServerException = exports.NoApiKeyProvidedException = void 0;
+exports.BadRequestException = exports.UnprocessableEntityException = exports.NotFoundException = exports.UnauthorizedException = exports.GenericServerException = exports.NoSigningKeyProvidedException = exports.NoApiKeyProvidedException = void 0;
 class NoApiKeyProvidedException extends Error {
     constructor() {
         super(...arguments);
@@ -11,6 +11,17 @@ class NoApiKeyProvidedException extends Error {
     }
 }
 exports.NoApiKeyProvidedException = NoApiKeyProvidedException;
+class NoSigningKeyProvidedException extends Error {
+    constructor() {
+        super(...arguments);
+        this.status = 500;
+        this.name = "NoSigningKeyProvidedException";
+        this.message = `Missing or invalid signing key key. Pass it as an option to Knock.signUserToken(userId, {signingKey: "S25vY2sga25vY2sh..."}) ` +
+            `or define it in the KNOCK_SIGNING_KEY environment variable. The signing key can either be a Base-64 encoded string ` +
+            `or a PEM-encoded certificate. For more information, see https://docs.knock.app/in-app-ui/security-and-authentication#authentication-with-enhanced-security-enabled`;
+    }
+}
+exports.NoSigningKeyProvidedException = NoSigningKeyProvidedException;
 class GenericServerException {
     constructor(status, message, requestID) {
         this.status = status;

package/dist/src/common/interfaces.d.ts

@@ -46,4 +46,12 @@ export interface Condition {
     variable: string;
     operator: string;
 }
+export interface SignUserTokenOptions {
+    /**
+     * The signing key to use to sign the token. If not provided, the KNOCK_SIGNING_KEY environment variable will be used.
+     */
+    signingKey?: string;
+    /** The expiration time of the token in seconds. Defaults to 1 hour. */
+    expiresInSeconds?: number;
+}
 export {};

package/dist/src/knock.d.ts

@@ -1,5 +1,5 @@
 import { AxiosResponse } from "axios";
-import { KnockOptions, PostAndPutOptions } from "./common/interfaces";
+import { KnockOptions, PostAndPutOptions, SignUserTokenOptions } from "./common/interfaces";
 import { Users } from "./resources/users";
 import { Preferences } from "./resources/preferences";
 import { Workflows } from "./resources/workflows";
@@ -22,6 +22,15 @@ declare class Knock {
     readonly tenants: Tenants;
     constructor(key?: string | undefined, options?: KnockOptions);
     notify(workflowKey: string, properties: TriggerWorkflowProperties): Promise<import("./resources/workflows/interfaces").WorkflowRun>;
+    /**
+     * 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 {string} A JWT token that can be used to authenticate requests to the Knock API (e.g. by passing into the <KnockFeedProvider /> component)
+     */
+    static signUserToken(userId: string, options: SignUserTokenOptions): string;
     post(path: string, entity: any, options?: PostAndPutOptions): Promise<AxiosResponse>;
     put(path: string, entity: any, options?: PostAndPutOptions): Promise<AxiosResponse>;
     delete(path: string, entity?: any): Promise<AxiosResponse>;

package/dist/src/knock.js

@@ -14,6 +14,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Knock = void 0;
 const axios_1 = __importDefault(require("axios"));
+const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
 const package_json_1 = require("../package.json");
 const exceptions_1 = require("./common/exceptions");
 const users_1 = require("./resources/users");
@@ -57,6 +58,29 @@ class Knock {
             return this.workflows.trigger(workflowKey, properties);
         });
     }
+    /**
+     * 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 {string} A JWT token that can be used to authenticate requests to the Knock API (e.g. by passing into the <KnockFeedProvider /> component)
+     */
+    static signUserToken(userId, options) {
+        var _a;
+        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 = (_a = options.expiresInSeconds) !== null && _a !== void 0 ? _a : 60 * 60;
+        return jsonwebtoken_1.default.sign({
+            sub: userId,
+            iat: currentTime,
+            exp: currentTime + expireInSeconds,
+        }, signingKey, {
+            algorithm: "RS256",
+        });
+    }
     post(path, entity, options = {}) {
         return __awaiter(this, void 0, void 0, function* () {
             try {
@@ -144,3 +168,14 @@ class Knock {
     }
 }
 exports.Knock = Knock;
+function prepareSigningKey(key) {
+    const maybeSigningKey = key !== null && key !== void 0 ? key : process.env.KNOCK_SIGNING_KEY;
+    if (!maybeSigningKey)
+        throw new exceptions_1.NoSigningKeyProvidedException();
+    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 exceptions_1.NoSigningKeyProvidedException();
+}

package/dist/src/resources/objects/index.d.ts

@@ -1,6 +1,6 @@
 import { ChannelData, CommonMetadata, SetChannelDataProperties, PaginatedResponse, ChannelType } from "../../common/interfaces";
 import { Knock } from "../../knock";
-import { BulkSetObjectOption, ListObjectOptions, Object, SetObjectProperties } from "./interfaces";
+import { AddObjectSubscriptionProperties, BulkSetObjectOption, DeleteObjectSubscriptionProperties, ListObjectOptions, ListObjectSubscriptionsOptions, Object, ObjectSubscription, SetObjectProperties } from "./interfaces";
 import { BulkOperation } from "../bulk_operations/interfaces";
 import { ListMessagesOptions, Message } from "../messages/interfaces";
 import { ChannelTypePreferences, PreferenceOptions, PreferenceSet, SetPreferencesProperties, WorkflowPreferences, WorkflowPreferenceSetting } from "../preferences/interfaces";
@@ -30,4 +30,7 @@ export declare class Objects {
     setWorkflowPreferences(collection: string, objectId: string, workflowKey: string, setting: WorkflowPreferenceSetting, options?: PreferenceOptions): Promise<PreferenceSet>;
     setCategoriesPreferences(collection: string, objectId: string, categoryPreferences: WorkflowPreferences, options?: PreferenceOptions): Promise<PreferenceSet>;
     setCategoryPreferences(collection: string, objectId: string, categoryKey: string, setting: WorkflowPreferenceSetting, options?: PreferenceOptions): Promise<PreferenceSet>;
+    listSubscriptions(collection: string, objectId: string, options?: ListObjectSubscriptionsOptions): Promise<PaginatedResponse<ObjectSubscription>>;
+    addSubscriptions(collection: string, objectId: string, properties?: AddObjectSubscriptionProperties): Promise<ObjectSubscription[]>;
+    deleteSubscriptions(collection: string, objectId: string, properties?: DeleteObjectSubscriptionProperties): Promise<ObjectSubscription[]>;
 }

package/dist/src/resources/objects/index.js

@@ -160,5 +160,26 @@ class Objects {
             return data;
         });
     }
+    //
+    // Subscriptions
+    //
+    listSubscriptions(collection, objectId, options = {}) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { data } = yield this.knock.get(`/v1/objects/${collection}/${objectId}/subscriptions`, options);
+            return data;
+        });
+    }
+    addSubscriptions(collection, objectId, properties = { recipients: [] }) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { data } = yield this.knock.post(`/v1/objects/${collection}/${objectId}/subscriptions`, properties);
+            return data;
+        });
+    }
+    deleteSubscriptions(collection, objectId, properties = { recipients: [] }) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { data } = yield this.knock.delete(`/v1/objects/${collection}/${objectId}/subscriptions`, properties);
+            return data;
+        });
+    }
 }
 exports.Objects = Objects;

package/dist/src/resources/objects/interfaces.d.ts

@@ -1,4 +1,6 @@
 import { CommonMetadata, PaginationOptions } from "../../common/interfaces";
+import { User } from "../users/interfaces";
+import { Recipient, RecipientWithUpsert } from "../workflows/interfaces";
 export interface ObjectRef {
     collection: string;
     id: string;
@@ -23,3 +25,18 @@ export interface ListObjectOptions extends PaginationOptions {
     object_id?: string;
     name?: string;
 }
+export interface ListObjectSubscriptionsOptions extends PaginationOptions {
+}
+export interface ObjectSubscription<T = CommonMetadata> {
+    recipient: User | Object;
+    properties: T;
+    inserted_at: string;
+    updated_at: string;
+}
+export interface AddObjectSubscriptionProperties {
+    recipients: (Recipient | RecipientWithUpsert)[];
+    properties?: CommonMetadata;
+}
+export interface DeleteObjectSubscriptionProperties {
+    recipients: Recipient[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knocklabs/node",
-  "version": "0.4.14",
+  "version": "0.4.16",
   "description": "Library for interacting with the Knock API",
   "homepage": "https://github.com/knocklabs/knock-node",
   "author": "@knocklabs",
@@ -32,6 +32,7 @@
   },
   "devDependencies": {
     "@types/jest": "26.0.23",
+    "@types/jsonwebtoken": "^9.0.1",
     "@types/node": "^15.0.1",
     "@types/pluralize": "0.0.29",
     "axios-mock-adapter": "1.19.0",
@@ -43,6 +44,7 @@
     "typescript": "4.2.4"
   },
   "dependencies": {
-    "axios": "^0.21.1"
+    "axios": "^0.21.1",
+    "jsonwebtoken": "^9.0.0"
   }
 }