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

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";
 

client/src/configuration.ts

@@ -1,18 +1,26 @@
+/**
+     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;
   integrationName: string;
   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;
 
 /**

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);
@@ -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;

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<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,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=<your-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=<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: "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.

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)

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)

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)