From 3817831577684dd9a76ee4b3c423c9666ce7e9dd Mon Sep 17 00:00:00 2001 From: Tuan Dang Date: Sat, 22 Apr 2023 14:34:05 +0300 Subject: [PATCH] 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