@superartifacts/sdk 0.1.0 → 0.1.1

package/README.md

@@ -1,7 +1,10 @@
 # @superartifacts/sdk
 
 The TypeScript SDK for the [Super Artifacts](https://superartifacts.app) REST API. No runtime
-dependencies. Node 20.3+, Bun, Deno and Cloudflare Workers.
+dependencies.
+
+Node 20.3+. It uses only the standard `fetch`, so other runtimes that provide it may work; only
+Node is tested.
 
 ```bash
 npm install @superartifacts/sdk
@@ -9,6 +12,8 @@ npm install @superartifacts/sdk
 
 **Server-side only.** The API refuses any request carrying an `Origin` header, which means every
 browser, and a key on a page is a leaked key. The client throws if you construct it in a browser.
+`dangerouslyAllowBrowser: true` turns that check off for use behind your own proxy, and ships the
+key to every visitor.
 
 ## Quickstart
 
@@ -43,9 +48,12 @@ Every method takes one object holding the operation's path, query and body field
 optional second argument for this request alone:
 
 ```ts
-await sa.artifacts.update({ artifact: 'hello', visibility: 'private' }, { timeout: 10_000 })
+await sa.artifacts.update({ artifact: 'hello', visibility: 'private' }, { timeout: 30_000 })
 ```
 
+Responses are untyped JSON until the API describes them: every result is an open object, so
+destructure and index it without a cast.
+
 Resources: `account`, `artifacts`, `live`, `uploads`, `data`, `schema`, `entries`, `secrets`,
 `templates`, `projects`, `shares`, `comments`, `mentions`, `signatures`.
 
@@ -66,12 +74,13 @@ Per request: `{ idempotencyKey, timeout, signal, headers }`.
 ## Errors
 
 Every failure is a `SuperArtifactsError` with `status`, `code`, `message` and, when the API asked
-you to wait, `retryAfter` in seconds. Anything else the API said is in `details`.
+you to wait, `retryAfter` in seconds. Anything else the API said is in `details`. A missing key
+throws before any request, so that `AuthenticationError` has no `status` or `code`.
 
 | Class | When |
 | --- | --- |
 | `InvalidArgumentsError` | 400 |
-| `AuthenticationError` | 401 |
+| `AuthenticationError` | 401, or no key to send |
 | `PlanLimitError` | 402 |
 | `PermissionError` | 403 `forbidden` |
 | `ScopeRequiredError` | 403 `scope_required`: a read key called a write |

package/dist/index.cjs

@@ -53,8 +53,8 @@ var SuperArtifactsError = class extends Error {
   constructor(status, code, message, retryAfter, details = {}, options) {
     super(message, options);
     this.name = new.target.name;
-    this.status = status;
-    this.code = code;
+    if (status !== void 0) this.status = status;
+    if (code !== void 0) this.code = code;
     if (retryAfter !== void 0) this.retryAfter = retryAfter;
     this.details = details;
   }
@@ -121,7 +121,7 @@ function errorFor(status, text, retryAfterHeader) {
 }
 
 // src/core.ts
-var VERSION = "0.1.0";
+var VERSION = "0.1.1";
 var DEFAULT_BASE_URL = "https://superartifacts.app";
 var API_KEY_ENV = "SUPERARTIFACTS_API_KEY";
 var MAX_RETRY_AFTER_SECONDS = 60;
@@ -160,8 +160,10 @@ var Core = class {
     }
     const apiKey = options.apiKey ?? globalThis.process?.env?.[API_KEY_ENV];
     if (!apiKey) {
-      throw new Error(
-        `No API key. Set ${API_KEY_ENV} or pass { apiKey }. Create one at https://superartifacts.app/settings/api-keys`
+      throw new AuthenticationError(
+        void 0,
+        void 0,
+        `No API key. Pass { apiKey } or set ${API_KEY_ENV}. Create one at https://superartifacts.app/settings/api-keys.`
       );
     }
     this.#apiKey = apiKey;
@@ -235,7 +237,8 @@ var Core = class {
         const text = await response.text();
         if (response.ok) return parseAnswer(text, response.status);
         failure = errorFor(response.status, text, response.headers.get("retry-after"));
-        const { status, retryAfter } = failure;
+        const { status } = response;
+        const { retryAfter } = failure;
         if (status === 429 || retry && [502, 503, 504].includes(status)) {
           if (retryAfter !== void 0) delay = retryAfter * 1e3;
           retry = left && (retryAfter ?? 0) <= MAX_RETRY_AFTER_SECONDS;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-declare const VERSION = "0.1.0";
+declare const VERSION = "0.1.1";
 interface ClientOptions {
     /** Defaults to the SUPERARTIFACTS_API_KEY environment variable. */
     apiKey?: string;
@@ -45,6 +45,13 @@ type Query<Op> = Op extends {
 } ? [NonNullable<Q>] extends [never] ? object : NonNullable<Q> : object;
 /** Path, query and body fields of an operation, in one object. */
 type Params<Op> = Path<Op> & Query<Op> & Body<Op>;
+type JsonObject = {
+    [key: string]: any;
+};
+/** R's named properties, without the index signature an open object carries. */
+type Declared<R> = keyof {
+    [K in keyof R as string extends K ? never : K]: unknown;
+};
 type Result<Op> = Op extends {
     responses: {
         200: {
@@ -53,7 +60,7 @@ type Result<Op> = Op extends {
             };
         };
     };
-} ? R : unknown;
+} ? [Declared<R>] extends [never] ? JsonObject : R : unknown;
 declare class Core {
     #private;
     constructor(options?: ClientOptions);
@@ -70,16 +77,19 @@ declare class Core {
     protected send(url: URL | string, init: RequestInit, repeatable: boolean, options?: RequestOptions): Promise<Record<string, unknown>>;
 }
 
-/** Anything this SDK throws for a failed call. `status` is 0 when no answer arrived. */
+/**
+ * Anything this SDK throws for a failed call. `status` is 0 when no answer arrived, and it
+ * and `code` are absent when no request was made: an `AuthenticationError` for a missing key.
+ */
 declare class SuperArtifactsError extends Error {
-    readonly status: number;
+    readonly status?: number;
     /** Stable and machine-readable; `message` is for a person. */
-    readonly code: string;
+    readonly code?: string;
     /** Seconds the API asked to wait. */
     readonly retryAfter?: number;
     /** Everything else the API said, e.g. `fix` or `approvalUrl`. */
     readonly details: Record<string, unknown>;
-    constructor(status: number, code: string, message: string, retryAfter?: number, details?: Record<string, unknown>, options?: ErrorOptions);
+    constructor(status: number | undefined, code: string | undefined, message: string, retryAfter?: number, details?: Record<string, unknown>, options?: ErrorOptions);
 }
 declare class InvalidArgumentsError extends SuperArtifactsError {
 }
@@ -2349,7 +2359,7 @@ declare class Resources extends Core {
     readonly signatures: SignaturesResource;
 }
 
-type Row = Record<string, unknown>;
+type Row = JsonObject;
 declare class Data extends DataResource {
     /** Every row `listArtifactRows` matches, page by page. */
     iterArtifactRows(params: Params<operations['listArtifactRows']>, options?: RequestOptions): AsyncGenerator<Row>;
@@ -2386,4 +2396,4 @@ declare class SuperArtifacts extends Resources {
 }
 
 export { AuthenticationError, ConflictError, ConnectionError, InternalError, InvalidArgumentsError, NotFoundError, OPERATIONS, PayloadTooLargeError, PermissionError, PlanLimitError, RateLimitError, ScopeRequiredError, SuperArtifacts, SuperArtifactsError, TimeoutError, VERSION, SuperArtifacts as default, errorFor };
-export type { ClientOptions, FileToUpload, Operation, Params, RequestOptions, Result, components, operations };
+export type { ClientOptions, FileToUpload, JsonObject, Operation, Params, RequestOptions, Result, components, operations };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-declare const VERSION = "0.1.0";
+declare const VERSION = "0.1.1";
 interface ClientOptions {
     /** Defaults to the SUPERARTIFACTS_API_KEY environment variable. */
     apiKey?: string;
@@ -45,6 +45,13 @@ type Query<Op> = Op extends {
 } ? [NonNullable<Q>] extends [never] ? object : NonNullable<Q> : object;
 /** Path, query and body fields of an operation, in one object. */
 type Params<Op> = Path<Op> & Query<Op> & Body<Op>;
+type JsonObject = {
+    [key: string]: any;
+};
+/** R's named properties, without the index signature an open object carries. */
+type Declared<R> = keyof {
+    [K in keyof R as string extends K ? never : K]: unknown;
+};
 type Result<Op> = Op extends {
     responses: {
         200: {
@@ -53,7 +60,7 @@ type Result<Op> = Op extends {
             };
         };
     };
-} ? R : unknown;
+} ? [Declared<R>] extends [never] ? JsonObject : R : unknown;
 declare class Core {
     #private;
     constructor(options?: ClientOptions);
@@ -70,16 +77,19 @@ declare class Core {
     protected send(url: URL | string, init: RequestInit, repeatable: boolean, options?: RequestOptions): Promise<Record<string, unknown>>;
 }
 
-/** Anything this SDK throws for a failed call. `status` is 0 when no answer arrived. */
+/**
+ * Anything this SDK throws for a failed call. `status` is 0 when no answer arrived, and it
+ * and `code` are absent when no request was made: an `AuthenticationError` for a missing key.
+ */
 declare class SuperArtifactsError extends Error {
-    readonly status: number;
+    readonly status?: number;
     /** Stable and machine-readable; `message` is for a person. */
-    readonly code: string;
+    readonly code?: string;
     /** Seconds the API asked to wait. */
     readonly retryAfter?: number;
     /** Everything else the API said, e.g. `fix` or `approvalUrl`. */
     readonly details: Record<string, unknown>;
-    constructor(status: number, code: string, message: string, retryAfter?: number, details?: Record<string, unknown>, options?: ErrorOptions);
+    constructor(status: number | undefined, code: string | undefined, message: string, retryAfter?: number, details?: Record<string, unknown>, options?: ErrorOptions);
 }
 declare class InvalidArgumentsError extends SuperArtifactsError {
 }
@@ -2349,7 +2359,7 @@ declare class Resources extends Core {
     readonly signatures: SignaturesResource;
 }
 
-type Row = Record<string, unknown>;
+type Row = JsonObject;
 declare class Data extends DataResource {
     /** Every row `listArtifactRows` matches, page by page. */
     iterArtifactRows(params: Params<operations['listArtifactRows']>, options?: RequestOptions): AsyncGenerator<Row>;
@@ -2386,4 +2396,4 @@ declare class SuperArtifacts extends Resources {
 }
 
 export { AuthenticationError, ConflictError, ConnectionError, InternalError, InvalidArgumentsError, NotFoundError, OPERATIONS, PayloadTooLargeError, PermissionError, PlanLimitError, RateLimitError, ScopeRequiredError, SuperArtifacts, SuperArtifactsError, TimeoutError, VERSION, SuperArtifacts as default, errorFor };
-export type { ClientOptions, FileToUpload, Operation, Params, RequestOptions, Result, components, operations };
+export type { ClientOptions, FileToUpload, JsonObject, Operation, Params, RequestOptions, Result, components, operations };

package/dist/index.js

@@ -10,8 +10,8 @@ var SuperArtifactsError = class extends Error {
   constructor(status, code, message, retryAfter, details = {}, options) {
     super(message, options);
     this.name = new.target.name;
-    this.status = status;
-    this.code = code;
+    if (status !== void 0) this.status = status;
+    if (code !== void 0) this.code = code;
     if (retryAfter !== void 0) this.retryAfter = retryAfter;
     this.details = details;
   }
@@ -78,7 +78,7 @@ function errorFor(status, text, retryAfterHeader) {
 }
 
 // src/core.ts
-var VERSION = "0.1.0";
+var VERSION = "0.1.1";
 var DEFAULT_BASE_URL = "https://superartifacts.app";
 var API_KEY_ENV = "SUPERARTIFACTS_API_KEY";
 var MAX_RETRY_AFTER_SECONDS = 60;
@@ -117,8 +117,10 @@ var Core = class {
     }
     const apiKey = options.apiKey ?? globalThis.process?.env?.[API_KEY_ENV];
     if (!apiKey) {
-      throw new Error(
-        `No API key. Set ${API_KEY_ENV} or pass { apiKey }. Create one at https://superartifacts.app/settings/api-keys`
+      throw new AuthenticationError(
+        void 0,
+        void 0,
+        `No API key. Pass { apiKey } or set ${API_KEY_ENV}. Create one at https://superartifacts.app/settings/api-keys.`
       );
     }
     this.#apiKey = apiKey;
@@ -192,7 +194,8 @@ var Core = class {
         const text = await response.text();
         if (response.ok) return parseAnswer(text, response.status);
         failure = errorFor(response.status, text, response.headers.get("retry-after"));
-        const { status, retryAfter } = failure;
+        const { status } = response;
+        const { retryAfter } = failure;
         if (status === 429 || retry && [502, 503, 504].includes(status)) {
           if (retryAfter !== void 0) delay = retryAfter * 1e3;
           retry = left && (retryAfter ?? 0) <= MAX_RETRY_AFTER_SECONDS;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superartifacts/sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "The TypeScript SDK for the Super Artifacts REST API: publish artifacts, read their data, and manage projects, shares and templates from a server.",
   "license": "MIT",
   "type": "module",