From 3817831577684dd9a76ee4b3c423c9666ce7e9dd Mon Sep 17 00:00:00 2001 From: Tuan Dang Date: Sat, 22 Apr 2023 14:34:05 +0300 Subject: [PATCH 1/4] Update docs for upcoming Node SDK update --- docs/sdks/languages/node.mdx | 159 +++++++++++++++++++++++++---------- 1 file changed, 113 insertions(+), 46 deletions(-) diff --git a/docs/sdks/languages/node.mdx b/docs/sdks/languages/node.mdx index 58002392f..fe5e969f8 100644 --- a/docs/sdks/languages/node.mdx +++ b/docs/sdks/languages/node.mdx @@ -14,13 +14,13 @@ npm install infisical-node --save ## Initialization -Set up the Infisical client asynchronously as early as possible in your application by importing and initializing the global instance with `infisical.connect(options)`. +Call `connect()` with your Infisical token as early as possible in the main entry module of your application. This initializes the global instance of the SDK, which can be accessed anywhere in your application. -This methods fetches back all the secrets in the project and environment accessible by the token passed in `options`. +For multiple Infisical projects or creating multiple SDK instances, use `createConnection()` instead. This returns a local SDK instance, independent of the global instance. ### infisical.connect(options) -Updates the global instance of the Infisical client with a connection to an Infisical project and fetches back secrets if supplied with an [Infisical Token](/getting-started/dashboard/token). +Updates the global instance of the Infisical client with a connection to an Infisical project with the [Infisical Token](/getting-started/dashboard/token). @@ -36,18 +36,18 @@ Updates the global instance of the Infisical client with a connection to an Infi Your self-hosted absolute site URL including the protocol (e.g. `https://app.infisical.com`) + + Time-to-live (in seconds) for cached secrets. If set to 0, data is cached indefinitely. + Whether or not debug mode is on - - Whether or not to attach fetched secrets to `process.env` - ### infisical.createConnection(options) -Returns a local instance of the Infisical client with a connection to an Infisical project and fetches back secrets if supplied with an [Infisical Token](/getting-started/dashboard/token). +Returns a local instance of the Infisical client with a connection to an Infisical project with an [Infisical Token](/getting-started/dashboard/token). This method is useful if you wish to connect to two or more Infisical projects within your app. @@ -65,6 +65,9 @@ This method is useful if you wish to connect to two or more Infisical projects w Your self-hosted absolute site URL including the protocol (e.g. `https://app.infisical.com`) + + Time-to-live (in seconds) for cached secrets. If set to 0, data is cached indefinitely. + Whether or not debug mode is on @@ -76,15 +79,11 @@ This method is useful if you wish to connect to two or more Infisical projects w ```js import infisical from "infisical-node"; - const main = async () => { - await infisical.connect({ - token: "your_infisical_token", - }); + infisical.connect({ + token: "your_infisical_token", + }); - // your app logic - } - - main(); + // your app logic ``` @@ -93,14 +92,10 @@ This method is useful if you wish to connect to two or more Infisical projects w const infisical = require("infisical-node"); infisical.connect({ - token: "your_infisical_token" - }) - .then(() => { - // your application logic - }) - .catch(err => { - console.error('Error: ', err); - }) + token: "your_infisical_token" + }); + + // your app logic ```` @@ -108,45 +103,117 @@ This method is useful if you wish to connect to two or more Infisical projects w ## Usage -To get the value of a secret, use `infisical.get(key)`. +### infisical.getSecret(secretName, options) -### infisical.get(key) +Retrieve a secret from Infisical. -Return the value of the secret with the specified `key`. Note that the Infisical client falls back to `process.env` if `token` is `undefined` during the -initialization step or if a value for the secret is not found in the fetched secrets. +By default, `getSecret()` returns a personal secret. If not found, it returns a shared secret, or tries to retrieve the value from `process.env`. - - The key of the secret + + The key of the secret to retrieve + + + + + "personal" (default) or "shared". + + ```js -const value = infisical.get("SOME_KEY"); +const secret = await infisical.getSecret("API_KEY"); +const value = secret.secretValue; // get its value +``` + +### infisical.createSecret(secretName, secretValue, options) + +Create a new secret in Infisical. + + + The key of the secret to create + + + The value of the secret to create + + + + + "shared" (default) or "personal". A personal secret can only be created if a shared secret with the same name exists. + + + + +```js +const newApiKey = await infisical.createSecret("API_KEY", "FOO"); +``` + +### infisical.updateSecret(secretName, secretValue, options) + +Update an existing secret in Infisical. + + + The key of the secret to update + + + The new value of the secret + + + + + "shared" (default) or "personal". + + + + +```js +const updatedApiKey = await infisical.updateSecret("API_KEY", "BAR"); +``` + +### infisical.deleteSecret(secretName, options) + +Delete a secret in Infisical. + + + The key of the secret to delete + + + + + "shared" (default) or "personal". Note that deleting a shared secret also deletes all associated personal secrets. + + + + +```js +const deletedSecret = await infisical.deleteSecret("API_KEY"); ``` ## Example with Express ```js -const express = require("express"); -const port = 3000; -const infisical = require("infisical-node"); +import infisical from "infisical-node"; +import express from "express"; +const app = express(); +const PORT = 3000; -const main = async () => { - await infisical.connect({ - token: "st.xxx.xxx", - }); +infisical.connect({ + token: "YOUR_INFISICAL_TOKEN" +}); - // your application logic +app.get("/", async (req, res) => { + // access value + const name = await infisical.getSecret("NAME"); + res.send(`Hello! My name is: ${name.secretValue}`); +}); - app.get("/", (req, res) => { - res.send(`Howdy, ${infisical.get("NAME")}!`); - }); - - app.listen(port, async () => { - console.log(`App listening on port ${port}`); - }); -}; +app.listen(PORT, async () => { + // initialize client + console.log(`App listening on port ${port}`); +}); ``` +This example demonstrates how to use the Infisical SDK with an Express application. The application retrieves a secret named "NAME" and responds to requests with a greeting that includes the secret value. + We do not recommend hardcoding your [Infisical Token](/getting-started/dashboard/token). Setting it as an environment From a7484f8be5b7be0e50da2f541d1682a45af7b77c Mon Sep 17 00:00:00 2001 From: Tuan Dang Date: Sun, 23 Apr 2023 09:49:21 +0300 Subject: [PATCH 2/4] Update node SDK docs, positioning of examples --- docs/getting-started/quickstart.mdx | 36 ++++++----- docs/sdks/languages/node.mdx | 97 +++++++++++++++-------------- 2 files changed, 69 insertions(+), 64 deletions(-) diff --git a/docs/getting-started/quickstart.mdx b/docs/getting-started/quickstart.mdx index f19bd1120..8a2ef75f5 100644 --- a/docs/getting-started/quickstart.mdx +++ b/docs/getting-started/quickstart.mdx @@ -64,7 +64,9 @@ These examples demonstrate how to store and fetch environment variables from [In ### Initialize the Infisical client ```js - await infisical.connect({ + import infisical from "infisical-node"; + + infisical.connect({ token: "your_infisical_token", }); ``` @@ -72,31 +74,31 @@ These examples demonstrate how to store and fetch environment variables from [In ### Get a value ```js - const value = infisical.get("SOME_KEY"); + const value = await infisical.getSecret("SOME_KEY"); ``` ### Example with Express ```js - const express = require("express"); - const port = 3000; - const infisical = require("infisical-node"); + import infisical from "infisical-node"; + import express from "express"; + const app = express(); + const PORT = 3000; - const main = async () => { - await infisical.connect({ - token: "st.xxx.xxx", - }); + await infisical.connect({ + token: "st.xxx.xxx", + }); - // your application logic + // your application logic - app.get("/", (req, res) => { - res.send(`Howdy, ${infisical.get("NAME")}!`); - }); + app.get("/", async (req, res) => { + const name = await infisical.getSecret("NAME"); + res.send(`Hello! My name is: ${name.secretValue}`); + }); - app.listen(port, async () => { - console.log(`App listening on port ${port}`); - }); - }; + app.listen(PORT, async () => { + console.log(`App listening on port ${port}`); + }); ``` diff --git a/docs/sdks/languages/node.mdx b/docs/sdks/languages/node.mdx index fe5e969f8..28ce8cf00 100644 --- a/docs/sdks/languages/node.mdx +++ b/docs/sdks/languages/node.mdx @@ -2,7 +2,7 @@ title: "Node" --- -If you're working with Node.js, the official [infisical-node](https://github.com/Infisical/infisical-node) package is the easiest way to fetch secrets for your application. +If you're working with Node.js, the official [infisical-node](https://github.com/Infisical/infisical-node) package is the easiest way to fetch and work with ecrets for your application. ## Installation @@ -12,14 +12,42 @@ Run `npm` to add `infisical-node` to your project. npm install infisical-node --save ``` -## Initialization +## Configuration -Call `connect()` with your Infisical token as early as possible in the main entry module of your application. This initializes the global instance of the SDK, which can be accessed anywhere in your application. +Import the SDK and call `connect()` with your Infisical token as early as possible in the main entry module of your application. This initializes the global instance of the SDK, which can be accessed anywhere in your application. For multiple Infisical projects or creating multiple SDK instances, use `createConnection()` instead. This returns a local SDK instance, independent of the global instance. ### infisical.connect(options) + + + + ```js + import infisical from "infisical-node"; + + infisical.connect({ + token: "your_infisical_token", + }); + + // your app logic + ``` + + + + ```js + const infisical = require("infisical-node"); + + infisical.connect({ + token: "your_infisical_token" + }); + + // your app logic + ```` + + + + Updates the global instance of the Infisical client with a connection to an Infisical project with the [Infisical Token](/getting-started/dashboard/token). @@ -37,7 +65,7 @@ Updates the global instance of the Infisical client with a connection to an Infi `https://app.infisical.com`) - Time-to-live (in seconds) for cached secrets. If set to 0, data is cached indefinitely. + Time-to-live (in seconds) for refreshing cached secrets. Default: `300`. Whether or not debug mode is on @@ -74,41 +102,21 @@ This method is useful if you wish to connect to two or more Infisical projects w - - - ```js - import infisical from "infisical-node"; - - infisical.connect({ - token: "your_infisical_token", - }); - - // your app logic - ``` - - - - ```js - const infisical = require("infisical-node"); - - infisical.connect({ - token: "your_infisical_token" - }); - - // your app logic - ```` - - - ## Usage ### infisical.getSecret(secretName, options) +```js +const secret = await infisical.getSecret("API_KEY"); +const value = secret.secretValue; // get its value +``` + Retrieve a secret from Infisical. By default, `getSecret()` returns a personal secret. If not found, it returns a shared secret, or tries to retrieve the value from `process.env`. + The key of the secret to retrieve @@ -120,13 +128,12 @@ By default, `getSecret()` returns a personal secret. If not found, it returns a -```js -const secret = await infisical.getSecret("API_KEY"); -const value = secret.secretValue; // get its value -``` - ### infisical.createSecret(secretName, secretValue, options) +```js +const newApiKey = await infisical.createSecret("API_KEY", "FOO"); +``` + Create a new secret in Infisical. @@ -143,12 +150,12 @@ Create a new secret in Infisical. -```js -const newApiKey = await infisical.createSecret("API_KEY", "FOO"); -``` - ### infisical.updateSecret(secretName, secretValue, options) +```js +const updatedApiKey = await infisical.updateSecret("API_KEY", "BAR"); +``` + Update an existing secret in Infisical. @@ -165,12 +172,12 @@ Update an existing secret in Infisical. -```js -const updatedApiKey = await infisical.updateSecret("API_KEY", "BAR"); -``` - ### infisical.deleteSecret(secretName, options) +```js +const deletedSecret = await infisical.deleteSecret("API_KEY"); +``` + Delete a secret in Infisical. @@ -184,10 +191,6 @@ Delete a secret in Infisical. -```js -const deletedSecret = await infisical.deleteSecret("API_KEY"); -``` - ## Example with Express ```js From aacdaf4556053c74f9d4a750716eb974d7ef54dc Mon Sep 17 00:00:00 2001 From: Tuan Dang Date: Sun, 23 Apr 2023 12:45:13 +0300 Subject: [PATCH 3/4] Modify Node SDK docs to be inline with new initializer --- docs/sdks/languages/node.mdx | 57 +++++++----------------------------- 1 file changed, 10 insertions(+), 47 deletions(-) diff --git a/docs/sdks/languages/node.mdx b/docs/sdks/languages/node.mdx index 28ce8cf00..5a51afc79 100644 --- a/docs/sdks/languages/node.mdx +++ b/docs/sdks/languages/node.mdx @@ -14,20 +14,15 @@ npm install infisical-node --save ## Configuration -Import the SDK and call `connect()` with your Infisical token as early as possible in the main entry module of your application. This initializes the global instance of the SDK, which can be accessed anywhere in your application. - -For multiple Infisical projects or creating multiple SDK instances, use `createConnection()` instead. This returns a local SDK instance, independent of the global instance. - -### infisical.connect(options) - +Import the SDK and create a client instance with your Infisical token. ```js - import infisical from "infisical-node"; - - infisical.connect({ - token: "your_infisical_token", + import InfisicalClient from "infisical-node"; + + const client = new InfisicalClient({ + token: "your_infisical_token" }); // your app logic @@ -36,9 +31,9 @@ For multiple Infisical projects or creating multiple SDK instances, use `createC ```js - const infisical = require("infisical-node"); + const InfisicalClient = require("infisical-node"); - infisical.connect({ + const client = new InfisicalClient({ token: "your_infisical_token" }); @@ -48,8 +43,6 @@ For multiple Infisical projects or creating multiple SDK instances, use `createC -Updates the global instance of the Infisical client with a connection to an Infisical project with the [Infisical Token](/getting-started/dashboard/token). - @@ -73,36 +66,6 @@ Updates the global instance of the Infisical client with a connection to an Infi -### infisical.createConnection(options) - -Returns a local instance of the Infisical client with a connection to an Infisical project with an [Infisical Token](/getting-started/dashboard/token). - -This method is useful if you wish to connect to two or more Infisical projects within your app. - - - - - An [Infisical Token](/getting-started/dashboard/token) scoped to a project - and environment - - - Your self-hosted absolute site URL including the protocol (e.g. - `https://app.infisical.com`) - - - Time-to-live (in seconds) for cached secrets. If set to 0, data is cached indefinitely. - - - Whether or not debug mode is on - - - - - ## Usage ### infisical.getSecret(secretName, options) @@ -194,18 +157,18 @@ Delete a secret in Infisical. ## Example with Express ```js -import infisical from "infisical-node"; +import InfisicalClient from "infisical-node"; import express from "express"; const app = express(); const PORT = 3000; -infisical.connect({ +const client = new InfisicalClient({ token: "YOUR_INFISICAL_TOKEN" }); app.get("/", async (req, res) => { // access value - const name = await infisical.getSecret("NAME"); + const name = await client.getSecret("NAME"); res.send(`Hello! My name is: ${name.secretValue}`); }); From 9e42a7a33e10638822ed34d846099acb7d2ec908 Mon Sep 17 00:00:00 2001 From: Tuan Dang Date: Sun, 23 Apr 2023 15:51:42 +0300 Subject: [PATCH 4/4] Update quickstart example --- docs/getting-started/quickstart.mdx | 12 ++++++------ docs/sdks/languages/node.mdx | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/getting-started/quickstart.mdx b/docs/getting-started/quickstart.mdx index 8a2ef75f5..7fca86d4d 100644 --- a/docs/getting-started/quickstart.mdx +++ b/docs/getting-started/quickstart.mdx @@ -64,9 +64,9 @@ These examples demonstrate how to store and fetch environment variables from [In ### Initialize the Infisical client ```js - import infisical from "infisical-node"; + import InfisicalClient from "infisical-node"; - infisical.connect({ + const client = new InfisicalClient({ token: "your_infisical_token", }); ``` @@ -74,25 +74,25 @@ These examples demonstrate how to store and fetch environment variables from [In ### Get a value ```js - const value = await infisical.getSecret("SOME_KEY"); + const value = await client.getSecret("SOME_KEY"); ``` ### Example with Express ```js - import infisical from "infisical-node"; + import InfisicalClient from "infisical-node"; import express from "express"; const app = express(); const PORT = 3000; - await infisical.connect({ + const client = InfisicalClient({ token: "st.xxx.xxx", }); // your application logic app.get("/", async (req, res) => { - const name = await infisical.getSecret("NAME"); + const name = await client.getSecret("NAME"); res.send(`Hello! My name is: ${name.secretValue}`); }); diff --git a/docs/sdks/languages/node.mdx b/docs/sdks/languages/node.mdx index 5a51afc79..cb56f50d4 100644 --- a/docs/sdks/languages/node.mdx +++ b/docs/sdks/languages/node.mdx @@ -2,7 +2,7 @@ title: "Node" --- -If you're working with Node.js, the official [infisical-node](https://github.com/Infisical/infisical-node) package is the easiest way to fetch and work with ecrets for your application. +If you're working with Node.js, the official [infisical-node](https://github.com/Infisical/infisical-node) package is the easiest way to fetch and work with secrets for your application. ## Installation