@parallelworks/client 7.119.0 → 7.120.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -25,6 +25,11 @@ export declare function acceptLanguageFromEnv(env?: Record<string, string | unde
25
25
  export declare function problemTypeUrl(error: ApiError, baseUrl: string): string | undefined;
26
26
  /** Prefix for Parallel Works API keys */
27
27
  export declare const API_KEY_PREFIX = "pwt_";
28
+ /**
29
+ * Prefix for opaque user tokens. Like an API key, a user token names its
30
+ * platform host; like a JWT, it is sent as a Bearer token.
31
+ */
32
+ export declare const USER_TOKEN_PREFIX = "pwut_";
28
33
  /** Error thrown when credential parsing fails */
29
34
  export declare class CredentialError extends Error {
30
35
  constructor(message: string);
@@ -39,21 +44,23 @@ export declare class CredentialError extends Error {
39
44
  */
40
45
  export declare function isApiKey(credential: string): boolean;
41
46
  /**
42
- * Check if a credential is a JWT token.
47
+ * Check if a credential is a token, sent as a Bearer token.
43
48
  *
44
- * JWTs have three base64-encoded parts separated by dots.
49
+ * Tokens are opaque user tokens (starting with "pwut_") or JWTs, which have
50
+ * three base64-encoded parts separated by dots.
45
51
  *
46
52
  * @param credential - The credential string to check
47
- * @returns True if the credential appears to be a JWT token
53
+ * @returns True if the credential appears to be a token
48
54
  */
49
55
  export declare function isToken(credential: string): boolean;
50
56
  /**
51
- * Extract the platform host from an API key or JWT token.
57
+ * Extract the platform host from an API key or token.
52
58
  *
53
- * For API keys (pwt_xxxx.yyyy): decodes the first part after pwt_ to get the host
59
+ * For API keys (pwt_xxxx.yyyy) and opaque user tokens (pwut_xxxx.yyyy): decodes
60
+ * the first part after the prefix to get the host
54
61
  * For JWT tokens: decodes the payload (second segment) and reads platform_host field
55
62
  *
56
- * @param credential - The API key or JWT token
63
+ * @param credential - The API key or token
57
64
  * @returns The platform host (e.g., "activate.parallel.works")
58
65
  * @throws CredentialError if the credential format is invalid
59
66
  */
@@ -89,7 +96,7 @@ export declare class Client {
89
96
  * Create a client using only a credential.
90
97
  *
91
98
  * The platform host is automatically extracted from the credential:
92
- * - For API keys: host is decoded from the first part after pwt_
99
+ * - For API keys and opaque user tokens: host is decoded from the first part after the prefix
93
100
  * - For JWT tokens: host is read from the platform_host claim
94
101
  *
95
102
  * @param credential - Your API key or JWT token
@@ -128,7 +135,7 @@ export declare class Client {
128
135
  * Authenticate with automatic credential type detection
129
136
  *
130
137
  * Automatically detects whether the credential is an API key (starts with "pwt_")
131
- * or a JWT token and configures the appropriate authentication method.
138
+ * or a token and configures the appropriate authentication method.
132
139
  *
133
140
  * @param credential - Your API key or JWT token
134
141
  * @returns Configured API client ready to make requests
package/dist/index.js CHANGED
@@ -31,6 +31,11 @@ export function problemTypeUrl(error, baseUrl) {
31
31
  }
32
32
  /** Prefix for Parallel Works API keys */
33
33
  export const API_KEY_PREFIX = 'pwt_';
34
+ /**
35
+ * Prefix for opaque user tokens. Like an API key, a user token names its
36
+ * platform host; like a JWT, it is sent as a Bearer token.
37
+ */
38
+ export const USER_TOKEN_PREFIX = 'pwut_';
34
39
  /** Error thrown when credential parsing fails */
35
40
  export class CredentialError extends Error {
36
41
  constructor(message) {
@@ -50,45 +55,52 @@ export function isApiKey(credential) {
50
55
  return credential.trim().startsWith(API_KEY_PREFIX);
51
56
  }
52
57
  /**
53
- * Check if a credential is a JWT token.
58
+ * Check if a credential is a token, sent as a Bearer token.
54
59
  *
55
- * JWTs have three base64-encoded parts separated by dots.
60
+ * Tokens are opaque user tokens (starting with "pwut_") or JWTs, which have
61
+ * three base64-encoded parts separated by dots.
56
62
  *
57
63
  * @param credential - The credential string to check
58
- * @returns True if the credential appears to be a JWT token
64
+ * @returns True if the credential appears to be a token
59
65
  */
60
66
  export function isToken(credential) {
61
67
  const trimmed = credential.trim();
68
+ if (trimmed.startsWith(USER_TOKEN_PREFIX)) {
69
+ return true;
70
+ }
62
71
  const parts = trimmed.split('.');
63
72
  return parts.length === 3 && !trimmed.startsWith(API_KEY_PREFIX);
64
73
  }
65
74
  /**
66
- * Extract the platform host from an API key or JWT token.
75
+ * Extract the platform host from an API key or token.
67
76
  *
68
- * For API keys (pwt_xxxx.yyyy): decodes the first part after pwt_ to get the host
77
+ * For API keys (pwt_xxxx.yyyy) and opaque user tokens (pwut_xxxx.yyyy): decodes
78
+ * the first part after the prefix to get the host
69
79
  * For JWT tokens: decodes the payload (second segment) and reads platform_host field
70
80
  *
71
- * @param credential - The API key or JWT token
81
+ * @param credential - The API key or token
72
82
  * @returns The platform host (e.g., "activate.parallel.works")
73
83
  * @throws CredentialError if the credential format is invalid
74
84
  */
75
85
  export function extractPlatformHost(credential) {
76
86
  credential = credential.trim();
77
87
  if (isApiKey(credential)) {
78
- return extractHostFromApiKey(credential);
88
+ return extractEncodedHost(credential, API_KEY_PREFIX);
89
+ }
90
+ if (credential.startsWith(USER_TOKEN_PREFIX)) {
91
+ return extractEncodedHost(credential, USER_TOKEN_PREFIX);
79
92
  }
80
93
  if (isToken(credential)) {
81
94
  return extractHostFromToken(credential);
82
95
  }
83
96
  throw new CredentialError('Invalid credential format');
84
97
  }
85
- function extractHostFromApiKey(apiKey) {
86
- // Remove pwt_ prefix
87
- const withoutPrefix = apiKey.slice(API_KEY_PREFIX.length);
98
+ function extractEncodedHost(credential, prefix) {
99
+ const withoutPrefix = credential.slice(prefix.length);
88
100
  // Split by dot
89
101
  const dotIndex = withoutPrefix.indexOf('.');
90
102
  if (dotIndex === -1) {
91
- throw new CredentialError('Invalid API key format');
103
+ throw new CredentialError('Invalid credential format');
92
104
  }
93
105
  const encodedHost = withoutPrefix.slice(0, dotIndex);
94
106
  // Decode base64 (handle both browser and Node.js)
@@ -115,11 +127,11 @@ function extractHostFromApiKey(apiKey) {
115
127
  }
116
128
  }
117
129
  catch (e) {
118
- throw new CredentialError(`Could not decode API key host: ${e}`);
130
+ throw new CredentialError(`Could not decode credential host: ${e}`);
119
131
  }
120
132
  }
121
133
  if (!host) {
122
- throw new CredentialError('No platform host in API key');
134
+ throw new CredentialError('No platform host in credential');
123
135
  }
124
136
  return host;
125
137
  }
@@ -190,7 +202,7 @@ export class Client {
190
202
  * Create a client using only a credential.
191
203
  *
192
204
  * The platform host is automatically extracted from the credential:
193
- * - For API keys: host is decoded from the first part after pwt_
205
+ * - For API keys and opaque user tokens: host is decoded from the first part after the prefix
194
206
  * - For JWT tokens: host is read from the platform_host claim
195
207
  *
196
208
  * @param credential - Your API key or JWT token
@@ -249,7 +261,7 @@ export class Client {
249
261
  * Authenticate with automatic credential type detection
250
262
  *
251
263
  * Automatically detects whether the credential is an API key (starts with "pwt_")
252
- * or a JWT token and configures the appropriate authentication method.
264
+ * or a token and configures the appropriate authentication method.
253
265
  *
254
266
  * @param credential - Your API key or JWT token
255
267
  * @returns Configured API client ready to make requests
@@ -1,5 +1,5 @@
1
1
  import { describe, expect, it } from 'vitest';
2
- import { acceptLanguageFromEnv, Client, problemMediaType, problemTypeUrl, toApiError, } from './index';
2
+ import { acceptLanguageFromEnv, Client, extractPlatformHost, isApiKey, isToken, problemMediaType, problemTypeUrl, toApiError, USER_TOKEN_PREFIX, } from './index';
3
3
  function respond(status, body, contentType) {
4
4
  const requests = [];
5
5
  const fetch = async (input) => {
@@ -106,3 +106,22 @@ describe('acceptLanguageFromEnv', () => {
106
106
  expect(acceptLanguageFromEnv(env)).toBe(want);
107
107
  });
108
108
  });
109
+ describe('opaque user tokens', () => {
110
+ const token = `${USER_TOKEN_PREFIX}${btoa('activate.parallel.works')}.${btoa('raw')}`;
111
+ it('is a token, not an API key', () => {
112
+ expect(isToken(token)).toBe(true);
113
+ expect(isApiKey(token)).toBe(false);
114
+ });
115
+ it('names its platform host', () => {
116
+ expect(extractPlatformHost(token)).toBe('activate.parallel.works');
117
+ expect(() => extractPlatformHost(`${USER_TOKEN_PREFIX}no-dot`)).toThrow();
118
+ });
119
+ it('is sent as a Bearer token to the host it names', async () => {
120
+ const { fetch, requests } = respond(200, '[]', 'application/json');
121
+ const client = Client.fromCredential(token, { fetch });
122
+ await client.GET('/api/workflows');
123
+ const request = requests[0];
124
+ expect(new URL(request.url).host).toBe('activate.parallel.works');
125
+ expect(request.headers.get('Authorization')).toBe(`Bearer ${token}`);
126
+ });
127
+ });