@zapier/zapier-sdk 0.25.1 → 0.25.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @zapier/zapier-sdk
 
+## 0.25.2
+
+### Patch Changes
+
+- 642713b: Update README with more detail and more attention on fetch.
+
 ## 0.25.1
 
 ### Patch Changes

package/README.md

@@ -2,6 +2,8 @@
 
 ## Table of Contents
 
+- [Closed Beta](#closed-beta)
+- [Documentation](#documentation)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Available Functions](#available-functions)
@@ -31,10 +33,26 @@
 - [HTTP Requests](#http-requests)
   - [`fetch`](#fetch)
 
+## Closed Beta
+
+At the time of publishing this package, the Zapier SDK requires an invite for most features. If you want to try it out, let us know at the following page!
+
+https://sdk-beta.zapier.app/signup
+
+## Documentation
+
+The official documentation will soon be available at:
+
+https://docs.zapier.com/sdk
+
+While the dust settles, that documentation may be incomplete, and this README may have additional documentation.
+
+Agents are sometimes blocked from viewing docs on npm, so you may want to provide them a link to the official docs or copy the docs here into a prompt.
+
 ## Installation
 
 ```bash
-# If starting a new project:
+# If you're starting a new project:
 cd your-project-dir
 npm init -y
 npx tsc --init
@@ -46,20 +64,52 @@ npm install -D @zapier/zapier-sdk-cli @types/node typescript
 
 ## Quick Start
 
+Assuming you've installed the CLI package into your project (see instructions above), you (or an agent) can start using it right away. This is useful for introspecting actions, authentications, etc. that you want to use in code, but you can also use it to directly use integrations.
+
 ```bash
-# Authenticates through your browser, automatically handling token management
+# See all available commands
+npx zapier-sdk --help
+
+# Login to Zapier.
 npx zapier-sdk login
 
-# Generate TypeScript types for actions and fields of any apps you want to use.
-npx zapier-sdk add slack google-sheets
+# Search from thousands of supported apps.
+npx zapier-sdk list-apps --search "gmail"
+# The output will show you the valid keys next to the app title like this:
+# 1. Gmail (GoogleMailV2CLIAPI, gmail)
+
+# Run any action for the app, using one of the app keys.
+npx zapier-sdk run-action gmail
+# This will ask you for the type of action you want to run.
+# `search` or `write` are typically great for testing.
+# Note that you usually need an authentication (connection) to the app to run
+# the action. If you don't already have one, you can create a new one at:
+# https://zapier.com/app/assets/connections
+
+# List authentications for an app.
+npx zapier-sdk list-authentications gmail
+# Or only list the ones you own.
+npx zapier-sdk list-authentications gmail --owner me
+# Or just grab the first one.
+npx zapier-sdk find-first-authentication gmail --owner me
+
+# Make any API request to an app using your authentication (connection).
+npx zapier-sdk fetch "https://gmail.googleapis.com/gmail/v1/users/me/labels" --authentication-id 123
+```
 
-# The names of apps are there slugs if available, otherwise internal keys. If
-# you don't know the slug or key, just use `list-apps` search to find it.
-zapier-sdk list-apps --search "google sheets"
+The following is optional, but if you want to call our actions from code, it can be helpful to install TypeScript types for those actions. You can also just use `fetch` to make arbitrary API requests. In that case, you don't really need this, and instead you might need types or a good agent that will look up third party API docs.
 
+```bash
+# Search for apps that you want to use.
+npx zapier-sdk list-apps --search "slack"
+npx zapier-sdk list-apps --search "google sheets"
 # The output will show you the valid keys next to the app title like this:
+# 1. Slack (SlackCLIAPI, slack)
 # 1. Google Sheets (GoogleSheetsV2CLIAPI, google-sheets, google_sheets)
 
+# Generate TypeScript types for actions and fields of any apps you want to use.
+npx zapier-sdk add slack google-sheets
+
 # By default, types will be generated inside your `src` or `lib` folder if you
 # have one or otherwise the root folder. Make sure your `tsconfig.json` file
 # includes the generated type files.
@@ -68,20 +118,20 @@ zapier-sdk list-apps --search "google sheets"
 npx zapier-sdk add slack google-sheets --types-output ./types
 ```
 
+Now let's write some code!
+
 ```typescript
 import { createZapierSdk } from "@zapier/zapier-sdk";
 
 // ######## Initialize Zapier SDK ########
-// Option 1: Running `zapier-sdk login` authenticates through your browser,
-// automatically handling token management.
+// Option 1: Running `zapier-sdk login` authenticates through your browser and
+// stores a token on your local machine. As long as you have the CLI package
+// installed as a development dependency, the SDK will automatically use it.
 const zapier = createZapierSdk();
 
-// Option 2: Manually provide a token.
-// const zapier = createZapierSdk({
-//   credentials: "your_zapier_token_here", // or use ZAPIER_CREDENTIALS env var
-// });
-
-// Option 3: Manually provide a client ID and client secret.
+// Option 2: Provide a client ID and client secret.
+// You can get these by running `zapier-sdk create-client-credentials`.
+// This allows you to run the SDK in a server/serverless environment.
 // const zapier = createZapierSdk({
 //   credentials: {
 //     clientId: "your_client_id_here", // or use ZAPIER_CREDENTIALS_CLIENT_ID env var
@@ -89,6 +139,12 @@ const zapier = createZapierSdk();
 //   },
 // });
 
+// Option 3: Provide a valid Zapier token.
+// This is for partner OAuth or internal Zapier use.
+// const zapier = createZapierSdk({
+//   credentials: "your_zapier_token_here", // or use ZAPIER_CREDENTIALS env var
+// });
+
 // ######## Access Apps ########
 // List methods return a promise for a page with {data, nextCursor}.
 const { data: firstPageApps, nextCursor } = await zapier.listApps();
@@ -165,7 +221,8 @@ console.log({
 });
 
 // Option 2: Access actions via the `apps` proxy
-// If you've generated TS types for an app using `zapier-sdk add`, you can access the app's actions like this:
+// If you've generated TS types for an app using `zapier-sdk add`, you can
+// access the app's actions like this:
 
 // await zapier.apps.slack.read.channles({});
 // await zapier.apps.slack.write.send_message({})
@@ -218,6 +275,18 @@ console.log({
 // For example, either of the following are valid:
 // zapier.apps["google-sheets"]
 // zapier.apps.google_sheets
+
+// We have tens of thousands of actions across thousands of apps, but you're
+// still not limited to those. You can make any arbitrary API request to an app
+// using the same authentications with `.fetch`! This returns a response just
+// like a normal `fetch` call in JavaScript.
+const emojiResponse = await zapier.fetch("https://slack.com/api/emoji.list", {
+  authenticationId: myAuths[0].id,
+});
+
+const emojiData = await emojiResponse.json();
+
+console.log(emojiData.emoji);
 ```
 
 ## Available Functions

package/dist/index.cjs

@@ -5155,7 +5155,7 @@ function getCpuTime() {
 
 // package.json
 var package_default = {
-  version: "0.25.1"};
+  version: "0.25.2"};
 
 // src/plugins/eventEmission/builders.ts
 function createBaseEvent(context = {}) {

package/dist/index.mjs

@@ -5133,7 +5133,7 @@ function getCpuTime() {
 
 // package.json
 var package_default = {
-  version: "0.25.1"};
+  version: "0.25.2"};
 
 // src/plugins/eventEmission/builders.ts
 function createBaseEvent(context = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zapier/zapier-sdk",
-  "version": "0.25.1",
+  "version": "0.25.2",
   "description": "Complete Zapier SDK - combines all Zapier SDK packages",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",