diff --git a/client/package.json b/client/package.json index b4b6fae..0a0bb24 100644 --- a/client/package.json +++ b/client/package.json @@ -8,13 +8,12 @@ "prettier": "prettier --check 'src/*.ts'", "prettier-fix": "prettier --write 'src/*.ts'", "eslint": "eslint -c .eslintrc.json 'src/*.ts'", - "prepare": "npm run build" + "prepare": "npm run build", + "gen-docs": "typedoc ./src/*.ts --out ../docs" }, "author": "1Password", "license": "MIT", - "files": [ - "./dist" - ], + "files": ["./dist"], "exports": { ".": { "types": "./dist/sdk.d.ts", @@ -40,6 +39,8 @@ "typescript": "^5.3.3", "@types/node": "^20.11.0", "@babel/preset-env": "^7.23.8", - "babel-jest": "^29.7.0" + "babel-jest": "^29.7.0", + "typedoc": "^0.25.12", + "typedoc-plugin-markdown": "^3.17.1" } } diff --git a/client/src/client.ts b/client/src/client.ts index 551e8c4..fb3734d 100644 --- a/client/src/client.ts +++ b/client/src/client.ts @@ -1,3 +1,7 @@ +/** + Module containing the 1Password SDK Client, which can be used to authenticate and access data stored in 1Password programmatically. + @module + */ import { InnerClient } from "./core.js"; import { SecretsApi, SecretsSource } from "./secrets.js"; diff --git a/client/src/configuration.ts b/client/src/configuration.ts index b7bd501..a304f7b 100644 --- a/client/src/configuration.ts +++ b/client/src/configuration.ts @@ -1,10 +1,16 @@ +/** + Module defining configuration options for the 1Password SDK. + @module + */ import * as os from "os"; import { ClientAuthConfig } from "./core.js"; const LANGUAGE = "JS"; const VERSION = "0010001"; // v0.1.0 -// Contains information necessary to configure an SDK client. +/** + Defines all parameters that can be used to configure the 1Password SDK Client. + */ export interface ClientConfiguration { // Auth currently only accepts a service account token. Read more about how to get started with service accounts: https://developer.1password.com/docs/service-accounts/get-started/#create-a-service-account auth: Auth; @@ -12,7 +18,9 @@ export interface ClientConfiguration { integrationVersion: string; } -// Sets the authentication method. Use a token as a `string` to authenticate with a service account token. +/** + Sets the authentication method. Supply a `string` to authenticate with a service account token. + */ type Auth = string; /** diff --git a/client/src/core.ts b/client/src/core.ts index e712129..2b36e5e 100644 --- a/client/src/core.ts +++ b/client/src/core.ts @@ -1,6 +1,13 @@ +/** + Internal module defining the 1Password SDK Core. Users of the SDK should import and use the `client` module instead of this one. + @internal + @module + */ import { init_client, invoke, release_client } from "@1password/sdk-core"; -// Exposes the SDK core to the host JS SDK. +/** + Exposes the SDK core to the host JS SDK. + */ export interface Core { // Allocates a new authenticated client and returns its id. initClient(config: ClientAuthConfig): Promise; @@ -10,7 +17,9 @@ export interface Core { releaseClient(clientId: number): void; } -// Wraps configuration information needed to allocate and authenticate a client instance and sends it to the SDK core. +/** + Wraps configuration information needed to allocate and authenticate a client instance and sends it to the SDK core. + */ export interface ClientAuthConfig { serviceAccountToken: string; programmingLanguage: string; @@ -24,14 +33,18 @@ export interface ClientAuthConfig { architecture: string; } -// Contains the information sent to the SDK core when you call (invoke) a function. +/** + Contains the information sent to the SDK core when you call (invoke) a function. + */ export interface InvokeConfig { // Identifies the client instance for which you called the function. clientId: number; invocation: Invocation; } -// Calls certain logic from the SDK core, with the given parameters. +/** + Calls certain logic from the SDK core, with the given parameters. + */ interface Invocation { // Functionality name name: string; @@ -39,7 +52,9 @@ interface Invocation { parameters: string; } -// An implementation of the `Core` interface that shares resources across all clients. +/** + An implementation of the `Core` interface that shares resources across all clients. + */ export class SharedCore implements Core { public async initClient(config: ClientAuthConfig): Promise { const serializedConfig = JSON.stringify(config); @@ -57,7 +72,10 @@ export class SharedCore implements Core { } } -// Represents the client instance on which a call is made. +/** + Represents the client instance on which a call is made. + @internal + */ export interface InnerClient { id: number; core: Core; diff --git a/client/src/secrets.ts b/client/src/secrets.ts index c9f1474..76e259a 100644 --- a/client/src/secrets.ts +++ b/client/src/secrets.ts @@ -1,19 +1,41 @@ +/** + Module defining the Secrets API. + The Secrets API can be used to access secrets stored in 1Password via secret references (op://vault/item/field). + It is implemented by the 1Passwor + */ import { InvokeConfig, InnerClient } from "./core.js"; -// Exposes functionality around secrets. +/** + Exposes functionality for retrieving secrets. + */ export interface SecretsApi { - // Takes as input a secret reference and returns the secret to which it points. + /** + Takes as input a secret reference and returns the secret to which it points. + @param secretReference - A string containing a secret reference (string of the form "op://vault/item/field"). + @returns The value of the referenced 1Password item field. + */ resolve(secretReference: string): Promise; } -// An implementation of the `SecretsAPI` that wraps a `Core`. +/** + @inheritdoc + */ export class SecretsSource implements SecretsApi { + /** + @internal + */ #inner: InnerClient; + /** + @internal + */ public constructor(inner: InnerClient) { this.#inner = inner; } + /** + @inheritdoc + */ public async resolve(secretReference: string): Promise { const invocationConfig: InvokeConfig = { clientId: this.#inner.id, diff --git a/client/typedoc.json b/client/typedoc.json new file mode 100644 index 0000000..02f36b9 --- /dev/null +++ b/client/typedoc.json @@ -0,0 +1,5 @@ +{ + "plugin": ["typedoc-plugin-markdown"], + "hideInPageTOC": true, + "excludeInternal": true +} diff --git a/docs/.nojekyll b/docs/.nojekyll new file mode 100644 index 0000000..e2ac661 --- /dev/null +++ b/docs/.nojekyll @@ -0,0 +1 @@ +TypeDoc added this file to prevent GitHub Pages from using Jekyll. You can turn off this behavior by setting the `githubPages` option to false. \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..2106789 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,71 @@ +@1password/sdk / [Modules](modules.md) + +# 1Password JavaScript SDK + +> ❗ This project is still in its early, pre-alpha stages of development. Its stability is not yet fully assessed, and future iterations may bring backwards incompatible changes. Proceed with caution. + +The 1Password JavaScript SDK offers programmatic read access to your secrets in 1Password in an interface native to JavaScript. The SDK currently supports `Node.JS` and authentication with [1Password Service Accounts](https://developer.1password.com/docs/service-accounts/). + +### Get started + +To use the 1Password JavaScript SDK in your project: + +1. [Create a 1Password Service Account](https://developer.1password.com/docs/service-accounts/get-started/#create-a-service-account). You can create service accounts if you're an owner or administrator on your team. Otherwise, ask your administrator for a service account token. +2. Export your service account token to the `OP_SERVICE_ACCOUNT_TOKEN` environment variable: + +```bash +export OP_SERVICE_ACCOUNT_TOKEN= +``` + +3. Edit your `.npmrc` file (in your $HOME or in your project directory) to include the following literal string: + +``` +//registry.npmjs.org/:_authToken=${NPM_TOKEN} +``` + +> ⚠️ The `.npmrc` file should contain literally the above string, you should not add your NPM token to this file! The token will be provisioned by the `npm` CLI from the environment variable set in the next step. + +4. Set the environment variable `NPM_TOKEN` to the private beta token provided by 1Password: + +```bash +export NPM_TOKEN= +``` + +5. Install the 1Password JavaScript SDK: + +```bash +## NPM +npm install @1password/sdk@0.1.0-beta.2 +``` + +```bash +## PNPM +pnpm add @1password/sdk@0.1.0-beta.2 +``` + +```bash +## Yarn +yarn add @1password/sdk@0.1.0-beta.2 +``` + +6. Use the SDK in your project: + +```js +import { createClient } from "@1password/sdk"; + +// Creates an authenticated client. +const client = await createClient({ + auth: process.env.OP_SERVICE_ACCOUNT_TOKEN, + integrationName: "My 1Password Integration", + integrationVersion: "v1.0.0", +}); + +// Fetches a secret. +const secret = await client.secrets.resolve("op://vault/item/field"); +``` + +Make sure to use [secret reference URIs](https://developer.1password.com/docs/cli/secret-references/) with the syntax `op://vault/item/field` to securely load secrets from 1Password into your code. + +Note: The SDK doesn't yet support using secret references with query parameters, so you can't use secret references to retrieve file attachments or SSH keys, or to get more information about field metadata. + +Inside `createClient()`, set `integrationName` to the name of your application and `integrationVersion` to the version of your application. diff --git a/docs/classes/client.Client.md b/docs/classes/client.Client.md new file mode 100644 index 0000000..1ade1d8 --- /dev/null +++ b/docs/classes/client.Client.md @@ -0,0 +1,35 @@ +[@1password/sdk](../README.md) / [Modules](../modules.md) / [client](../modules/client.md) / Client + +# Class: Client + +[client](../modules/client.md).Client + +## Constructors + +### constructor + +• **new Client**(`innerClient`): [`Client`](client.Client.md) + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `innerClient` | `InnerClient` | + +#### Returns + +[`Client`](client.Client.md) + +#### Defined in + +[client.ts:12](https://github.com/1Password/1password-js-sdk/blob/8f949b4/client/src/client.ts#L12) + +## Properties + +### secrets + +• **secrets**: [`SecretsApi`](../interfaces/secrets.SecretsApi.md) + +#### Defined in + +[client.ts:10](https://github.com/1Password/1password-js-sdk/blob/8f949b4/client/src/client.ts#L10) diff --git a/docs/classes/secrets.SecretsSource.md b/docs/classes/secrets.SecretsSource.md new file mode 100644 index 0000000..38085c0 --- /dev/null +++ b/docs/classes/secrets.SecretsSource.md @@ -0,0 +1,39 @@ +[@1password/sdk](../README.md) / [Modules](../modules.md) / [secrets](../modules/secrets.md) / SecretsSource + +# Class: SecretsSource + +[secrets](../modules/secrets.md).SecretsSource + +Exposes functionality for retrieving secrets. + +## Implements + +- [`SecretsApi`](../interfaces/secrets.SecretsApi.md) + +## Methods + +### resolve + +▸ **resolve**(`secretReference`): `Promise`\<`string`\> + +Takes as input a secret reference and returns the secret to which it points. + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `secretReference` | `string` | A string containing a secret reference (string of the form "op://vault/item/field"). | + +#### Returns + +`Promise`\<`string`\> + +The value of the referenced 1Password item field. + +#### Implementation of + +[SecretsApi](../interfaces/secrets.SecretsApi.md).[resolve](../interfaces/secrets.SecretsApi.md#resolve) + +#### Defined in + +[secrets.ts:39](https://github.com/1Password/1password-js-sdk/blob/8f949b4/client/src/secrets.ts#L39) diff --git a/docs/interfaces/configuration.ClientConfiguration.md b/docs/interfaces/configuration.ClientConfiguration.md new file mode 100644 index 0000000..ee07545 --- /dev/null +++ b/docs/interfaces/configuration.ClientConfiguration.md @@ -0,0 +1,37 @@ +[@1password/sdk](../README.md) / [Modules](../modules.md) / [configuration](../modules/configuration.md) / ClientConfiguration + +# Interface: ClientConfiguration + +[configuration](../modules/configuration.md).ClientConfiguration + +Defines all parameters that can be used to configure the 1Password SDK Client. + +## Properties + +### auth + +• **auth**: `string` + +#### Defined in + +[configuration.ts:16](https://github.com/1Password/1password-js-sdk/blob/8f949b4/client/src/configuration.ts#L16) + +___ + +### integrationName + +• **integrationName**: `string` + +#### Defined in + +[configuration.ts:17](https://github.com/1Password/1password-js-sdk/blob/8f949b4/client/src/configuration.ts#L17) + +___ + +### integrationVersion + +• **integrationVersion**: `string` + +#### Defined in + +[configuration.ts:18](https://github.com/1Password/1password-js-sdk/blob/8f949b4/client/src/configuration.ts#L18) diff --git a/docs/interfaces/secrets.SecretsApi.md b/docs/interfaces/secrets.SecretsApi.md new file mode 100644 index 0000000..69f7bf6 --- /dev/null +++ b/docs/interfaces/secrets.SecretsApi.md @@ -0,0 +1,35 @@ +[@1password/sdk](../README.md) / [Modules](../modules.md) / [secrets](../modules/secrets.md) / SecretsApi + +# Interface: SecretsApi + +[secrets](../modules/secrets.md).SecretsApi + +Exposes functionality for retrieving secrets. + +## Implemented by + +- [`SecretsSource`](../classes/secrets.SecretsSource.md) + +## Methods + +### resolve + +▸ **resolve**(`secretReference`): `Promise`\<`string`\> + +Takes as input a secret reference and returns the secret to which it points. + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `secretReference` | `string` | A string containing a secret reference (string of the form "op://vault/item/field"). | + +#### Returns + +`Promise`\<`string`\> + +The value of the referenced 1Password item field. + +#### Defined in + +[secrets.ts:17](https://github.com/1Password/1password-js-sdk/blob/8f949b4/client/src/secrets.ts#L17) diff --git a/docs/modules.md b/docs/modules.md new file mode 100644 index 0000000..2ce2ee1 --- /dev/null +++ b/docs/modules.md @@ -0,0 +1,11 @@ +[@1password/sdk](README.md) / Modules + +# @1password/sdk + +## Modules + +- [client](modules/client.md) +- [client\_builder](modules/client_builder.md) +- [configuration](modules/configuration.md) +- [sdk](modules/sdk.md) +- [secrets](modules/secrets.md) diff --git a/docs/modules/client.md b/docs/modules/client.md new file mode 100644 index 0000000..8b3dba1 --- /dev/null +++ b/docs/modules/client.md @@ -0,0 +1,9 @@ +[@1password/sdk](../README.md) / [Modules](../modules.md) / client + +# Module: client + +Module containing the 1Password SDK Client, which can be used to authenticate and access data stored in 1Password programmatically. + +## Classes + +- [Client](../classes/client.Client.md) diff --git a/docs/modules/client_builder.md b/docs/modules/client_builder.md new file mode 100644 index 0000000..e55733a --- /dev/null +++ b/docs/modules/client_builder.md @@ -0,0 +1,28 @@ +[@1password/sdk](../README.md) / [Modules](../modules.md) / client\_builder + +# Module: client\_builder + +## Functions + +### createClientWithCore + +▸ **createClientWithCore**(`config`, `core`): `Promise`\<[`Client`](../classes/client.Client.md)\> + +Creates a 1Password SDK client with a given core implementation. + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `config` | [`ClientConfiguration`](../interfaces/configuration.ClientConfiguration.md) | +| `core` | `Core` | + +#### Returns + +`Promise`\<[`Client`](../classes/client.Client.md)\> + +The authenticated 1Password SDK client. + +#### Defined in + +[client_builder.ts:15](https://github.com/1Password/1password-js-sdk/blob/8f949b4/client/src/client_builder.ts#L15) diff --git a/docs/modules/configuration.md b/docs/modules/configuration.md new file mode 100644 index 0000000..264a258 --- /dev/null +++ b/docs/modules/configuration.md @@ -0,0 +1,33 @@ +[@1password/sdk](../README.md) / [Modules](../modules.md) / configuration + +# Module: configuration + +Module defining configuration options for the 1Password SDK. + +## Interfaces + +- [ClientConfiguration](../interfaces/configuration.ClientConfiguration.md) + +## Functions + +### clientAuthConfig + +▸ **clientAuthConfig**(`userConfig`): `ClientAuthConfig` + +Creates a default client configuration. + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `userConfig` | [`ClientConfiguration`](../interfaces/configuration.ClientConfiguration.md) | + +#### Returns + +`ClientAuthConfig` + +The client configuration to instantiate the client with. + +#### Defined in + +[configuration.ts:30](https://github.com/1Password/1password-js-sdk/blob/8f949b4/client/src/configuration.ts#L30) diff --git a/docs/modules/sdk.md b/docs/modules/sdk.md new file mode 100644 index 0000000..1bc818a --- /dev/null +++ b/docs/modules/sdk.md @@ -0,0 +1,53 @@ +[@1password/sdk](../README.md) / [Modules](../modules.md) / sdk + +# Module: sdk + +## References + +### Client + +Re-exports [Client](../classes/client.Client.md) + +## Variables + +### DEFAULT\_INTEGRATION\_NAME + +• `Const` **DEFAULT\_INTEGRATION\_NAME**: ``"Unknown"`` + +#### Defined in + +[sdk.ts:6](https://github.com/1Password/1password-js-sdk/blob/8f949b4/client/src/sdk.ts#L6) + +___ + +### DEFAULT\_INTEGRATION\_VERSION + +• `Const` **DEFAULT\_INTEGRATION\_VERSION**: ``"Unknown"`` + +#### Defined in + +[sdk.ts:7](https://github.com/1Password/1password-js-sdk/blob/8f949b4/client/src/sdk.ts#L7) + +## Functions + +### createClient + +▸ **createClient**(`config`): `Promise`\<[`Client`](../classes/client.Client.md)\> + +Creates a default 1Password SDK client. + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `config` | [`ClientConfiguration`](../interfaces/configuration.ClientConfiguration.md) | + +#### Returns + +`Promise`\<[`Client`](../classes/client.Client.md)\> + +The authenticated 1Password SDK client. + +#### Defined in + +[sdk.ts:15](https://github.com/1Password/1password-js-sdk/blob/8f949b4/client/src/sdk.ts#L15) diff --git a/docs/modules/secrets.md b/docs/modules/secrets.md new file mode 100644 index 0000000..56c986d --- /dev/null +++ b/docs/modules/secrets.md @@ -0,0 +1,11 @@ +[@1password/sdk](../README.md) / [Modules](../modules.md) / secrets + +# Module: secrets + +## Classes + +- [SecretsSource](../classes/secrets.SecretsSource.md) + +## Interfaces + +- [SecretsApi](../interfaces/secrets.SecretsApi.md) diff --git a/package.json b/package.json index 1580de9..b2996fa 100644 --- a/package.json +++ b/package.json @@ -9,11 +9,8 @@ "prepare": "npm run build --workspace client", "prettier": "npm run prettier --workspaces --if-present", "prettier-fix": "npm run prettier-fix --workspaces --if-present", - "eslint": "npm run eslint --workspaces --if-present" + "eslint": "npm run eslint --workspaces --if-present", + "gen-docs": "npm run gen-docs --workspace client" }, - "workspaces": [ - "client", - "examples", - "wasm" - ] + "workspaces": ["client", "examples", "wasm"] }