Implement automated reference documentation generation

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/client.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"
   }
 }

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 * as os from "os";
 import { SecretsApi, SecretsSource } from "./secrets.js";
 import { ClientAuthConfig, Core, SharedCore } from "./core.js";

client/src/configuration.ts

@@ -1,17 +1,28 @@
+/**
+     Module defining configuration options for the 1Password SDK.
+    @module
+ */
 import { Core } from "./core.js";
 
-// 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;
 }
 
-// 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: Auth;
   integrationName: string;
   integrationVersion: string;
 }
 
-// Sets the authentication method. Use `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;

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<string>;
@@ -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,22 +33,28 @@ 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;
   // Parameters
   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<string> {
     const serializedConfig = JSON.stringify(config);

client/src/secrets.ts

@@ -1,20 +1,43 @@
+/**
+ 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 } from "./core.js";
 import { InnerClient } from "./configuration.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<string>;
 }
 
-// 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<string> {
     const invocationConfig: InvokeConfig = {
       clientId: this.#inner.id,

client/typedoc.json

@@ -0,0 +1,5 @@
+{
+  "plugin": ["typedoc-plugin-markdown"],
+  "hideInPageTOC": true,
+  "excludeInternal": true
+}

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.

docs/README.md

@@ -0,0 +1,65 @@
+@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). Make sure to grant the service account access to the vaults where the secrets your project needs access to are stored.
+2. Export your service account token to the `OP_SERVICE_ACCOUNT_TOKEN` environment variable:
+
+```bash
+export OP_SERVICE_ACCOUNT_TOKEN=<your-service-account-token>
+```
+
+3. Edit your `.npmrc` file (in your $HOME or in your project directory) to include the following: 
+
+```
+//registry.npmjs.org/:_authToken=${NPM_TOKEN}
+```
+
+4. Set the environment variable `NPM_TOKEN` to the private beta token provided by 1Password:
+
+```bash
+export NPM_TOKEN=<token-provided-by-1password-on-private-beta-registration>
+```
+
+5. Install the 1Password JavaScript SDK:
+
+```bash
+## NPM
+npm install @1password/[email protected]
+```
+
+```bash
+## PNPM
+pnpm add @1password/[email protected]
+```
+
+```bash
+## Yarn
+yarn add @1password/[email protected]
+```
+
+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: "<your_integration_name>",
+    integrationVersion: "<your_integration_version>",
+});
+
+// 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.

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:54](https://github.com/1Password/1password-js-sdk/blob/b037da5/client/src/client.ts#L54)
+
+## Properties
+
+### secrets
+
+• **secrets**: [`SecretsApi`](../interfaces/secrets.SecretsApi.md)
+
+#### Defined in
+
+[client.ts:52](https://github.com/1Password/1password-js-sdk/blob/b037da5/client/src/client.ts#L52)

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:41](https://github.com/1Password/1password-js-sdk/blob/b037da5/client/src/secrets.ts#L41)

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:20](https://github.com/1Password/1password-js-sdk/blob/b037da5/client/src/configuration.ts#L20)
+
+___
+
+### integrationName
+
+• **integrationName**: `string`
+
+#### Defined in
+
+[configuration.ts:21](https://github.com/1Password/1password-js-sdk/blob/b037da5/client/src/configuration.ts#L21)
+
+___
+
+### integrationVersion
+
+• **integrationVersion**: `string`
+
+#### Defined in
+
+[configuration.ts:22](https://github.com/1Password/1password-js-sdk/blob/b037da5/client/src/configuration.ts#L22)

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:19](https://github.com/1Password/1password-js-sdk/blob/b037da5/client/src/secrets.ts#L19)