@superartifacts/sdk 0.1.0 → 0.1.2

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 client-side
+failure has `status` 0 and its own `code`: a missing key is an `AuthenticationError` with `missing_api_key`.
 
 | 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

@@ -121,7 +121,7 @@ function errorFor(status, text, retryAfterHeader) {
 }
 
 // src/core.ts
-var VERSION = "0.1.0";
+var VERSION = "0.1.2";
 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(
+        0,
+        "missing_api_key",
+        `No API key. Pass { apiKey } or set ${API_KEY_ENV}. Create one at https://superartifacts.app/settings/api-keys.`
       );
     }
     this.#apiKey = apiKey;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-declare const VERSION = "0.1.0";
+declare const VERSION = "0.1.2";
 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);
@@ -2349,7 +2356,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 +2393,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.2";
 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);
@@ -2349,7 +2356,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 +2393,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

@@ -78,7 +78,7 @@ function errorFor(status, text, retryAfterHeader) {
 }
 
 // src/core.ts
-var VERSION = "0.1.0";
+var VERSION = "0.1.2";
 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(
+        0,
+        "missing_api_key",
+        `No API key. Pass { apiKey } or set ${API_KEY_ENV}. Create one at https://superartifacts.app/settings/api-keys.`
       );
     }
     this.#apiKey = apiKey;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superartifacts/sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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",