@cloudcannon/sdk 0.0.4 → 0.0.6

package/README.md

@@ -30,29 +30,49 @@ npm install @cloudcannon/sdk
 
 ## Creating and configuring the client
 
-Import `CloudCannonClient` and instantiate it with your API key:
+Import `CloudCannonClient` and instantiate it with your API key or user access key:
 
 ```typescript
 import CloudCannonClient from '@cloudcannon/sdk';
 
+// Authenticate with an API key
 const client = new CloudCannonClient({
   key: 'your-api-key-here',
 });
+
+// Authenticate with a user access key
+const client = new CloudCannonClient({
+  userAccessKey: {
+    id: 'your-access-key-id',
+    secret: 'your-access-key-secret',
+  },
+});
 ```
 
 ### Optional configuration
 
 | Option | Type | Description |
 |--------|------|-------------|
-| `key` | `string` | **Required.** Your CloudCannon API key. |
+| `key` | `string` | Your CloudCannon API key. Required if `userAccessKey` is not provided. |
+| `userAccessKey` | `{ id: string, secret: string }` | User access key for HMAC-SHA256 request signing. Required if `key` is not provided. |
 | `apiOrigin` | `string` | The API host. Defaults to `app.cloudcannon.com`. |
-| `getCustomAuthHeaders` | `() => Record<string, string>` | Provide custom authentication headers instead of the default `X-API-KEY`. |
+| `getCustomAuthHeaders` | `() => Record<string, string>` | Provide custom authentication headers instead of the default auth headers. |
 
 ```typescript
+// API key authentication
 const client = new CloudCannonClient({
   key: 'your-api-key-here',
   apiOrigin: 'app.cloudcannon.com',
 });
+
+// User access key authentication
+const client = new CloudCannonClient({
+  userAccessKey: {
+    id: 'your-access-key-id',
+    secret: 'your-access-key-secret',
+  },
+  apiOrigin: 'app.cloudcannon.com',
+});
 ```
 
 ## Client functions

package/dist/index.d.ts

@@ -9,6 +9,7 @@ import { type ConnectSiteOptions, type CreateDamOptions, type CreateInboxOptions
 import { type BuildConfiguration, type ConnectDamOptions, type ConnectInboxOptions, type CopySiteOptions, type CreateBackupOptions, type ListSiteBackupsOptions, type ListSiteBuildsOptions, type ListSiteSyncsOptions, SiteClient, type UpdateSiteOptions, type UploadFileOptions } from './src/site.ts';
 import { SiteInboxClient, type UpdateInboxOptions } from './src/site-inbox.ts';
 import { SyncClient } from './src/sync.ts';
+export { ApiError, AuthenticationError, } from './src/errors.ts';
 export type { BuildConfiguration, CommitEditingSessionOptions, CommitEditingSessionResponse, ConnectDamOptions, ConnectInboxOptions, ConnectSiteOptions, CopySiteOptions, CreateBackupOptions, CreateContributionOptions, CreateDamOptions, CreateEditingSessionFileOptions, CreateInboxOptions, FilterOptions, ListInboxSubmissionsOptions, ListOrgDamsOptions, ListOrgInboxesOptions, ListOrgSitesOptions, ListOrgsOptions, ListSiteBackupsOptions, ListSiteBuildsOptions, ListSiteSyncsOptions, PaginatedResponse, PaginationOptions, SortingOptions, UnlockOptions, UpdateInboxOptions, UpdateSiteOptions, UploadFileOptions, };
 export type Provider = operations['Providers_Repositories']['parameters']['path']['provider'];
 export type Site = components['schemas']['SiteBlueprint'];
@@ -72,15 +73,24 @@ type MatchURL<M extends keyof paths[keyof paths], U extends string> = {
 type ValidURL<M extends keyof paths[keyof paths], U extends string> = MatchURL<M, U> extends never ? {
     [K in keyof paths]: RequestParams<paths[K][M]> extends never ? never : StripPrefix<K>;
 }[keyof paths] : U;
-export type CloudCannonClientConfig = {
-    key: string;
+type BaseCloudCannonClientConfig = {
     apiOrigin?: string;
     getCustomAuthHeaders?: () => Record<string, string>;
 };
+export type CloudCannonClientConfig = ({
+    key: string;
+} & BaseCloudCannonClientConfig) | ({
+    userAccessKey: UserAccessKey;
+} & BaseCloudCannonClientConfig);
+export type UserAccessKey = {
+    id: string;
+    secret: string;
+};
 export default class CloudCannonClient {
     #private;
     constructor(config: CloudCannonClientConfig);
-    getAuthHeaders(): Record<string, string>;
+    getAuthHeaders(url: string, body?: string): Promise<Record<string, string>>;
+    signRequest(userAccessKey: UserAccessKey, url: string, body?: string | null): Promise<Record<string, string>>;
     fetch<const U extends string, const M extends Uppercase<keyof paths[keyof paths]> = 'GET'>(url: ValidURL<Lowercase<M>, U>, options?: Omit<RequestInit, keyof RequestMixin<M, MatchURL<Lowercase<M>, U>[Lowercase<M>]>> & RequestMixin<M, MatchURL<Lowercase<M>, U>[Lowercase<M>]>): Promise<APIResponse<MatchURL<Lowercase<M>, U>[Lowercase<M>]>>;
     org(uuid: string): OrgClient;
     site(uuid: string): SiteClient;

package/dist/index.js

@@ -1,50 +1,82 @@
+import { createHmac, randomUUID } from 'node:crypto';
 import { BackupClient } from "./src/backup.js";
 import { BuildClient } from "./src/build.js";
 import { EditingSessionClient, } from "./src/editing-session.js";
 import { EditingSessionFileClient, } from "./src/editing-session-file.js";
+import { AuthenticationError } from "./src/errors.js";
 import { buildQuery, paginatedResponse, } from "./src/helpers/query.js";
 import { InboxClient } from "./src/inbox.js";
 import { OrgClient, } from "./src/org.js";
 import { SiteClient, } from "./src/site.js";
 import { SiteInboxClient } from "./src/site-inbox.js";
 import { SyncClient } from "./src/sync.js";
+export { ApiError, AuthenticationError, } from "./src/errors.js";
 export default class CloudCannonClient {
     #apiKey;
+    #userAccessKey;
     #appDomain;
     #getCustomAuthHeaders;
     constructor(config) {
-        this.#apiKey = config.key;
+        if ('userAccessKey' in config) {
+            this.#userAccessKey = config.userAccessKey;
+        }
+        else {
+            this.#apiKey = config.key;
+        }
         this.#appDomain = config.apiOrigin ?? 'app.cloudcannon.com';
         this.#getCustomAuthHeaders = config.getCustomAuthHeaders;
     }
-    getAuthHeaders() {
+    async getAuthHeaders(url, body) {
         if (this.#getCustomAuthHeaders) {
-            return {
-                ...this.#getCustomAuthHeaders(),
-            };
+            return this.#getCustomAuthHeaders();
+        }
+        if (this.#userAccessKey) {
+            return this.signRequest(this.#userAccessKey, url, body);
         }
         return {
             'X-API-KEY': `${this.#apiKey}`,
         };
     }
+    async signRequest(userAccessKey, url, body) {
+        const signedAtISO = new Date().toISOString();
+        const nonce = randomUUID();
+        const key = Buffer.from(userAccessKey.secret, 'base64');
+        const message = JSON.stringify({ url, signed_at: signedAtISO, body: body ?? '', nonce });
+        const digest = createHmac('sha256', key).update(message).digest('hex');
+        return {
+            'X-CC-ACCESS-KEY': userAccessKey.id,
+            'X-CC-SIGNED-AT': signedAtISO,
+            'X-CC-CHECKSUM': digest,
+            'X-CC-NONCE': nonce,
+        };
+    }
     async fetch(url, options) {
+        const fullUrl = `https://${this.#appDomain}/api/v0${url}`;
+        let body;
+        if (options?.body) {
+            if (typeof options?.body !== 'string') {
+                body = JSON.stringify(options.body);
+            }
+            else {
+                body = options.body;
+            }
+        }
+        const authHeaders = await this.getAuthHeaders(fullUrl, body);
         const requestInit = {
             ...options,
             headers: {
-                ...this.getAuthHeaders(),
+                ...authHeaders,
                 'Content-Type': 'application/json',
+                'X-Requested-With': 'XMLHttpRequest',
                 ...options?.headers,
             },
+            body,
         };
-        if (options?.body) {
-            if (typeof options?.body !== 'string') {
-                requestInit.body = JSON.stringify(options.body);
-            }
-            else {
-                requestInit.body = options.body;
-            }
+        const resp = (await fetch(fullUrl, requestInit));
+        if (resp.status === 401) {
+            throw new AuthenticationError('Failed to authenticate with the CloudCannon API.', fullUrl, options);
         }
-        return fetch(`https://${this.#appDomain}/api/v0${url}`, requestInit);
+        return resp;
     }
     org(uuid) {
         return new OrgClient(uuid, this);
@@ -75,7 +107,7 @@ export default class CloudCannonClient {
     }
     async orgs(options = {}) {
         const query = buildQuery(options);
-        const resp = await this.fetch(`/orgs?${query}`);
+        const resp = await this.fetch(`/orgs${query}`);
         if (resp.status === 403) {
             throw new Error('Error fetching orgs. Permission denied');
         }

package/dist/src/errors.d.ts

@@ -5,3 +5,6 @@ export declare class ApiError extends Error {
     status: number | null;
     constructor(message: string, errors: unknown, url: string, options: unknown, status: number | null);
 }
+export declare class AuthenticationError extends ApiError {
+    constructor(message: string, url: string, options: unknown);
+}

package/dist/src/errors.js

@@ -11,3 +11,8 @@ export class ApiError extends Error {
         this.status = status;
     }
 }
+export class AuthenticationError extends ApiError {
+    constructor(message, url, options) {
+        super(message, undefined, url, options, 401);
+    }
+}

package/dist/src/helpers/query.d.ts

@@ -24,5 +24,5 @@ export declare function buildQuery(options?: PaginationOptions & {
     sort_attribute?: string;
     sort_direction?: 'ASC' | 'DESC';
     filters?: Record<string, unknown>;
-}): string;
+}): `?${string}` | '';
 export declare function paginatedResponse<T>(items: T[], headers: Headers): PaginatedResponse<T>;

package/dist/src/helpers/query.js

@@ -15,7 +15,11 @@ export function buildQuery(options = {}) {
             }
         }
     }
-    return params.toString();
+    const result = params.toString();
+    if (result.length > 0) {
+        return `?${result}`;
+    }
+    return '';
 }
 export function paginatedResponse(items, headers) {
     const parse = (name) => {

package/dist/src/inbox.js

@@ -8,7 +8,7 @@ export class InboxClient {
     }
     async getSubmissions(options = {}) {
         const query = buildQuery(options);
-        const resp = await this.#client.fetch(`/inboxes/${this.#uuid}/form-hooks?${query}`);
+        const resp = await this.#client.fetch(`/inboxes/${this.#uuid}/form-hooks${query}`);
         if (resp.status === 401 || resp.status === 403) {
             throw new Error('Error fetching submissions. Permission denied');
         }

package/dist/src/org.js

@@ -9,7 +9,7 @@ export class OrgClient {
     }
     async sites(options = {}) {
         const query = buildQuery(options);
-        const resp = await this.#client.fetch(`/orgs/${this.#uuid}/sites?${query}`);
+        const resp = await this.#client.fetch(`/orgs/${this.#uuid}/sites${query}`);
         if (resp.status === 401 || resp.status === 403) {
             throw new Error('Error fetching sites. Permission denied');
         }
@@ -67,7 +67,7 @@ export class OrgClient {
     }
     async getInboxes(options = {}) {
         const query = buildQuery(options);
-        const resp = await this.#client.fetch(`/orgs/${this.#uuid}/inboxes?${query}`);
+        const resp = await this.#client.fetch(`/orgs/${this.#uuid}/inboxes${query}`);
         if (resp.status === 403) {
             throw new Error('Error fetching inboxes. Permission denied');
         }
@@ -91,7 +91,7 @@ export class OrgClient {
     }
     async getDams(options = {}) {
         const query = buildQuery(options);
-        const resp = await this.#client.fetch(`/orgs/${this.#uuid}/dams?${query}`);
+        const resp = await this.#client.fetch(`/orgs/${this.#uuid}/dams${query}`);
         const dams = await resp.json();
         return paginatedResponse(dams, resp.headers);
     }

package/dist/src/site.js

@@ -73,7 +73,7 @@ export class SiteClient {
     }
     async getBuilds(options = {}) {
         const query = buildQuery(options);
-        const resp = await this.#client.fetch(`/sites/${this.#uuid}/builds?${query}`);
+        const resp = await this.#client.fetch(`/sites/${this.#uuid}/builds${query}`);
         if (resp.status === 401 || resp.status === 403) {
             throw new Error('Error fetching builds. Permission denied');
         }
@@ -90,7 +90,7 @@ export class SiteClient {
     }
     async listBackups(options = {}) {
         const query = buildQuery(options);
-        const resp = await this.#client.fetch(`/sites/${this.#uuid}/archives?${query}`);
+        const resp = await this.#client.fetch(`/sites/${this.#uuid}/archives${query}`);
         if (resp.status === 401) {
             throw new Error('Error fetching backups. Permission denied');
         }
@@ -140,7 +140,7 @@ export class SiteClient {
     }
     async getSyncs(options = {}) {
         const query = buildQuery(options);
-        const resp = await this.#client.fetch(`/sites/${this.#uuid}/syncs?${query}`);
+        const resp = await this.#client.fetch(`/sites/${this.#uuid}/syncs${query}`);
         if (resp.status === 401) {
             throw new Error('Error fetching syncs. Permission denied');
         }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cloudcannon/sdk",
   "type": "module",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "REST API client for the CloudCannon CMS.",
   "keywords": [
     "cloudcannon",