@1password/sdk 0.1.0-beta.3 → 0.1.0-beta.7

package/README.md

@@ -0,0 +1,92 @@
+<p align="center">
+  <a href="https://1password.com">
+      <h1 align="center">1Password JavaScript SDK (beta)</h1>
+  </a>
+</p>
+
+<p align="center">
+ <h4 align="center"> ❗ The 1Password SDK project is in beta. Future iterations may bring backwards-incompatible changes.</h4>
+</p>
+
+<p align="center">
+   <a href="https://developer.1password.com/docs/sdks/">Documentation</a> | <a href="https://github.com/1Password/onepassword-sdk-js/tree/main/examples">Examples</a>
+<br/>
+
+---
+
+The 1Password JavaScript SDK offers programmatic access to your secrets in 1Password with JavaScript. The SDK currently supports `Node.js`. During the beta, you can create, retrieve, update, and delete items and resolve secret references.
+
+## 🔑 Authentication
+
+1Password SDKs support authentication with [1Password Service Accounts](https://developer.1password.com/docs/service-accounts/get-started/). 
+
+Before you get started, [create a service account](https://developer.1password.com/docs/service-accounts/get-started/#create-a-service-account) and give it the appropriate permissions in the vaults where the items you want to use with the SDK are saved.
+
+## ❗ Limitations
+
+1Password SDKs don't yet support using secret references with query parameters, so you can't retrieve file attachments or SSH keys, or get more information about field metadata.
+
+1Password SDKs currently only support operations on text and concealed fields. As a result, you can't edit items that include information saved in other types of fields.
+
+When managing items with 1Password SDKs, you must use [unique identifiers (IDs)](https://developer.1password.com/docs/sdks/concepts#unique-identifiers) in place of vault, item, and field names.
+
+## 🚀 Get started
+
+To use the 1Password JavaScript SDK in your project:
+
+1. Provision your [service account](#authentication) token. We recommend provisioning your token from the environment. For example, to export your token to the `OP_SERVICE_ACCOUNT_TOKEN` environment variable:
+
+   **macOS or Linux**
+
+   ```bash
+   export OP_SERVICE_ACCOUNT_TOKEN=<your-service-account-token>
+   ```
+
+   **Windows**
+
+   ```powershell
+   $Env:OP_SERVICE_ACCOUNT_TOKEN = "<your-service-account-token>"
+   ```
+
+2. Install the 1Password JavaScript SDK in your project:
+
+   ```bash
+   ## NPM
+   npm install @1password/sdk@beta
+   ```
+
+   ```bash
+   ## PNPM
+   pnpm add @1password/sdk@beta
+   ```
+
+   ```bash
+   ## Yarn
+   yarn add @1password/sdk@beta
+   ```
+
+3. Use the JavaScript 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/secrets-reference-syntax/) with the syntax `op://vault/item/field` to securely load secrets from 1Password into your code.
+
+Inside `createClient()`, set `integrationName` to the name of your application and `integrationVersion` to the version of your application.
+
+## 📖 Learn more
+
+- [Load secrets with 1Password SDKs](https://developer.1password.com/docs/sdks/load-secrets)
+- [Manage items with 1Password SDKs](https://developer.1password.com/docs/sdks/manage-items)
+- [1Password SDK concepts](https://developer.1password.com/docs/sdks/concepts)

package/dist/configuration.d.ts

@@ -10,4 +10,5 @@ type Auth = string;
  * @returns The client configuration to instantiate the client with.
  */
 export declare const clientAuthConfig: (userConfig: ClientConfiguration) => ClientAuthConfig;
+export declare const getOsName: () => string;
 export {};

package/dist/configuration.js

@@ -23,7 +23,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.clientAuthConfig = void 0;
+exports.getOsName = exports.clientAuthConfig = void 0;
 const os = __importStar(require("os"));
 const LANGUAGE = "JS";
 const VERSION = "0010001"; // v0.1.0
@@ -42,10 +42,18 @@ const clientAuthConfig = (userConfig) => {
         integrationVersion: userConfig.integrationVersion,
         requestLibraryName: "Fetch API",
         requestLibraryVersion: "Fetch API",
-        // Only supported on Node.js
-        os: os.type().toLowerCase(),
+        os: (0, exports.getOsName)(),
         osVersion: defaultOsVersion,
         architecture: os.arch(),
     };
 };
 exports.clientAuthConfig = clientAuthConfig;
+const getOsName = () => {
+    // Only supported on Node.js
+    const os_name = os.type().toLowerCase();
+    if (os_name === "windows_nt") {
+        return "windows";
+    }
+    return os_name;
+};
+exports.getOsName = getOsName;

package/dist/core.d.ts

@@ -1,8 +1,23 @@
+/**
+ *  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>;
+    /**
+     *  Calls business logic from a given client and returns the result.
+     */
     invoke(config: InvokeConfig): Promise<string>;
+    /**
+     *  Deallocates memory held by the given client in the SDK core when it goes out of scope.
+     */
     releaseClient(clientId: number): void;
 }
+/**
+ *  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;
@@ -15,21 +30,42 @@ export interface ClientAuthConfig {
     osVersion: string;
     architecture: string;
 }
+/**
+ *  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.
+ */
 interface Invocation {
+    /**
+     *  Functionality name
+     */
     name: string;
+    /**
+     *  Parameters
+     */
     parameters: {
         [key: string]: unknown;
     };
 }
+/**
+ *  An implementation of the `Core` interface that shares resources across all clients.
+ */
 export declare class SharedCore implements Core {
     initClient(config: ClientAuthConfig): Promise<string>;
     invoke(config: InvokeConfig): Promise<string>;
     releaseClient(clientId: number): void;
 }
+/**
+ *  Represents the client instance on which a call is made.
+ */
 export interface InnerClient {
     id: number;
     core: Core;

package/dist/core.js

@@ -11,7 +11,9 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SharedCore = void 0;
 const sdk_core_1 = require("@1password/sdk-core");
-// An implementation of the `Core` interface that shares resources across all clients.
+/**
+ *  An implementation of the `Core` interface that shares resources across all clients.
+ */
 class SharedCore {
     initClient(config) {
         return __awaiter(this, void 0, void 0, function* () {

package/dist/items.d.ts

@@ -1,12 +1,28 @@
 import { InnerClient } from "./core.js";
 import * as types from "./types.js";
 export interface ItemsApi {
+    /**
+     *  Create a new item
+     */
     create(item: types.Item): Promise<types.Item>;
+    /**
+     *  Get an item by vault and item ID
+     */
     get(vaultId: string, itemId: string): Promise<types.Item>;
+    /**
+     *  Update an existing item. Warning: Only text and concealed fields are currently supported. Other fields will be permanently lost when you update an item.
+     */
+    update(item: types.Item): Promise<types.Item>;
+    /**
+     *  Delete an item. Warning:  Information saved in fields other than text and concealed fields will be permanently lost.
+     */
+    delete(vaultId: string, itemId: string): Promise<void>;
 }
 export declare class ItemsSource implements ItemsApi {
     #private;
     constructor(inner: InnerClient);
     create(item: types.Item): Promise<types.Item>;
     get(vaultId: string, itemId: string): Promise<types.Item>;
+    update(item: types.Item): Promise<types.Item>;
+    delete(vaultId: string, itemId: string): Promise<void>;
 }

package/dist/items.js

@@ -56,6 +56,35 @@ class ItemsSource {
             return JSON.parse(yield __classPrivateFieldGet(this, _ItemsSource_inner, "f").core.invoke(invocationConfig));
         });
     }
+    update(item) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const invocationConfig = {
+                clientId: __classPrivateFieldGet(this, _ItemsSource_inner, "f").id,
+                invocation: {
+                    name: "Update",
+                    parameters: {
+                        item,
+                    },
+                },
+            };
+            return JSON.parse(yield __classPrivateFieldGet(this, _ItemsSource_inner, "f").core.invoke(invocationConfig));
+        });
+    }
+    delete(vaultId, itemId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const invocationConfig = {
+                clientId: __classPrivateFieldGet(this, _ItemsSource_inner, "f").id,
+                invocation: {
+                    name: "Delete",
+                    parameters: {
+                        vault_id: vaultId,
+                        item_id: itemId,
+                    },
+                },
+            };
+            yield __classPrivateFieldGet(this, _ItemsSource_inner, "f").core.invoke(invocationConfig);
+        });
+    }
 }
 exports.ItemsSource = ItemsSource;
 _ItemsSource_inner = new WeakMap();

package/dist/sdk.d.ts

@@ -3,6 +3,7 @@ import { Client } from "./client.js";
 export declare const DEFAULT_INTEGRATION_NAME = "Unknown";
 export declare const DEFAULT_INTEGRATION_VERSION = "Unknown";
 export * from "./client.js";
+export * from "./types.js";
 /**
  * Creates a default 1Password SDK client.
  * @returns The authenticated 1Password SDK client.

package/dist/sdk.js

@@ -29,6 +29,7 @@ const client_builder_js_1 = require("./client_builder.js");
 exports.DEFAULT_INTEGRATION_NAME = "Unknown";
 exports.DEFAULT_INTEGRATION_VERSION = "Unknown";
 __exportStar(require("./client.js"), exports);
+__exportStar(require("./types.js"), exports);
 /**
  * Creates a default 1Password SDK client.
  * @returns The authenticated 1Password SDK client.

package/dist/types.d.ts

@@ -29,22 +29,70 @@ export declare enum ItemFieldType {
     Concealed = "Concealed",
     Unsupported = "Unsupported"
 }
+/**
+ *  Stores a field's title and value.
+ */
 export interface ItemField {
+    /**
+     *  The field's ID
+     */
     id: string;
+    /**
+     *  The field's title
+     */
     title: string;
+    /**
+     *  The ID of the section containing the field
+     */
     section_id?: string;
+    /**
+     *  The type of value stored in the field
+     */
     field_type: ItemFieldType;
+    /**
+     *  The string representation of the field's value
+     */
     value: string;
 }
+/**
+ *  A section groups together multiple fields in an item.
+ */
 export interface ItemSection {
+    /**
+     *  The ID of the section
+     */
     id: string;
+    /**
+     *  The title of the section
+     */
     title: string;
 }
+/**
+ *  Represents a 1Password item.
+ */
 export interface Item {
+    /**
+     *  The item's unique ID
+     */
     id: string;
+    /**
+     *  The item's title
+     */
     title: string;
+    /**
+     *  The item's category
+     */
     category: ItemCategory;
+    /**
+     *  The ID of the vault where the item is saved
+     */
     vault_id: string;
+    /**
+     *  The item's fields
+     */
     fields: ItemField[];
+    /**
+     *  The item's sections
+     */
     sections: ItemSection[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1password/sdk",
-  "version": "0.1.0-beta.3",
+  "version": "0.1.0-beta.7",
   "description": "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`",
   "scripts": {
     "build": "tsc",
@@ -8,7 +8,9 @@
     "prettier": "prettier --check 'src/*.ts'",
     "prettier-fix": "prettier --write 'src/*.ts'",
     "eslint": "eslint -c .eslintrc.json 'src/*.ts'",
-    "prepare": "npm run build"
+    "prepare": "rm -rf ./dist && npm run build",
+    "publish-test": "cp ../README.md . && npm publish --tag beta --dry-run && rm ./README.md",
+    "publish-beta": "cp ../README.md . && npm publish --tag beta && rm ./README.md"
   },
   "author": "1Password",
   "license": "MIT",
@@ -24,7 +26,7 @@
   "main": "./dist/sdk.js",
   "types": "./dist/sdk.d.ts",
   "dependencies": {
-    "@1password/sdk-core": "0.1.0-beta3"
+    "@1password/sdk-core": "0.1.0-beta.6"
   },
   "devDependencies": {
     "@1password/eslint-config": "^4.0.0",