SC26AI agents lab + dinner on the river · Nov 17
Parallel Works
View as Markdown
Share:

TypeScript SDK

@parallelworks/client is the official TypeScript client for the ACTIVATE platform API.

Installation

npm install @parallelworks/client

For SWR hooks support (React):

npm install @parallelworks/client swr swr-openapi

Quick Start

The simplest way to create a client is to pass your credential. The platform host is automatically extracted from it:

import { Client } from '@parallelworks/client'
 
const client = Client.fromCredential(process.env.PW_API_KEY!)
 
const { data, error } = await client.GET('/api/buckets')

Authentication

Signed in with pw auth

For scripts you run yourself, sign in with pw auth once, then create the client from the CLI's credentials file. The client uses your sign-in and renews it automatically by running pw auth token --print -o json, so the CLI must be installed and on your PATH.

import { Client } from '@parallelworks/client'
 
const client = Client.fromCredentialConfig()
 
const { data } = await client.GET('/api/buckets')

This needs Node.js 20.16 or later. The client uses the same context as the CLI: PW_API_KEY if set, then the context option, PW_CONTEXT, and the current context. The cliCommand option sets the path to pw. If pw can't renew the sign-in, requests reject with SignInExpiredError; run pw auth again.

For CI and other automation that runs without you, use an API key in PW_API_KEY instead.

Automatic Host Detection

An API key (pwt_...) contains your platform host, so fromCredential connects to it with no URL. An access token from pw auth token --print doesn't name a host: the client uses PW_PLATFORM_HOST if set, otherwise the server of the selected CLI context.

// API key: host decoded from the key
const client = Client.fromCredential('pwt_Y2xvdWQucGFyYWxsZWwud29ya3M.xxxxx')
// Connects to: https://cloud.parallel.works
 
// Access token from `pw auth token --print`: host from PW_PLATFORM_HOST,
// else the server of the selected context (Node.js)
const client = Client.fromCredential(token)

Explicit Host

If you prefer to specify the host explicitly:

// API key (Basic Auth) - for CI and other unattended automation
const client = new Client('https://cloud.parallel.works')
  .withApiKey('pwt_...')
 
// Access token (Bearer), sent as is and never renewed
const client = new Client('https://cloud.parallel.works')
  .withToken(token)
 
// Auto-detect credential type
const client = new Client('https://cloud.parallel.works')
  .withCredential(process.env.PW_CREDENTIAL!)

Credential Helpers

import { isApiKey, isToken, extractPlatformHost } from '@parallelworks/client'
 
isApiKey('pwt_abc.xyz')           // true
isToken('eyJ.abc.def')            // true
extractPlatformHost('pwt_...')    // "cloud.parallel.works"

SWR Hooks (React)

The client ships with optional SWR hooks for React applications:

// lib/api.ts
import { Client } from '@parallelworks/client'
import { createSwrHooks } from '@parallelworks/client/swr'
 
// Credential should be securely provided by your server (e.g., via session)
const client = Client.fromCredential(credential)
 
export const { useQuery, useImmutable, useInfinite } = createSwrHooks(client)
// components/BucketList.tsx
import { useQuery } from '@/lib/api'
 
export function BucketList() {
  const { data, error, isLoading } = useQuery('/api/buckets')
 
  if (isLoading) return <div>Loading...</div>
  if (error) return <div>Error: {error.message}</div>
 
  return (
    <ul>
      {data?.map(bucket => (
        <li key={bucket.id}>{bucket.name}</li>
      ))}
    </ul>
  )
}

Related Documentation