@interfere/sdk 8.1.0 → 8.1.6

package/CHANGELOG.md

@@ -0,0 +1,131 @@
+# @interfere/sdk
+
+## 8.1.6
+
+### Patch Changes
+
+- [#1665](https://github.com/interfere-inc/interfere/pull/1665) [`01e037e`](https://github.com/interfere-inc/interfere/commit/01e037e5dc3f6a013124dab44863d87a9be93029) Thanks [@skve](https://github.com/skve)! - Fix: fail releases with a warning if source map uploading fails
+
+## 8.1.2
+
+### Patch Changes
+
+- [`669f5e4`](https://github.com/interfere-inc/interfere/commit/669f5e40c24cf47b4335b8e51df09efe40112d29) Thanks [@skve](https://github.com/skve)! - Added telemetry for per-sdk breakdowns
+
+## 8.1.0
+
+### Minor Changes
+
+- [`e3b34e8`](https://github.com/interfere-inc/interfere/commit/e3b34e8bb42717aa5058286cb5683c0d8b068497) Thanks [@skve](https://github.com/skve)! - Added automatic country code detection & arbitrary trait support
+
+## 8.0.0
+
+### Major Changes
+
+- [`de35bcb`](https://github.com/interfere-inc/interfere/commit/de35bcbba7416339d95b4b98407e052046d6cce4) Thanks [@skve](https://github.com/skve)! - fixed race condition in session tracking
+
+## 6.0.0
+
+### Major Changes
+
+- [`4de11e1`](https://github.com/interfere-inc/interfere/commit/4de11e17a8a774139f47f06992b554370bae7150) Thanks [@skve](https://github.com/skve)! - Added remote config to plugin enablement
+
+## 5.0.0
+
+### Major Changes
+
+- [`2ef1592`](https://github.com/interfere-inc/interfere/commit/2ef1592e1b45422faf73bfd731509d6458fcfa07) Thanks [@skve](https://github.com/skve)! - User & Session Tracking support
+
+## 4.0.0
+
+### Major Changes
+
+- fix bundle
+
+## 1.0.3
+
+### Patch Changes
+
+- [`8102e08`](https://github.com/interfere-inc/interfere/commit/8102e0858d1e97953a62f76f0774511955c05422) Thanks [@skve](https://github.com/skve)! - Fixed catalog dependency resolution
+
+## 1.0.2
+
+### Patch Changes
+
+- fix types
+
+## 1.0.1
+
+### Patch Changes
+
+- [`032905b`](https://github.com/interfere-inc/interfere/commit/032905b19f2d916d4709251cf632957f127ca917) Thanks [@skve](https://github.com/skve)! - Fixed package exports
+
+## 1.0.0
+
+### Major Changes
+
+- [`17fe701`](https://github.com/interfere-inc/interfere/commit/17fe701227f2a55644eb77b254888a5a0657036d) Thanks [@skve](https://github.com/skve)! - feat: release v1
+
+### Minor Changes
+
+- [`949b3e2`](https://github.com/interfere-inc/interfere/commit/949b3e27002091477e4fdbd37e6c77d6de4ff780) Thanks [@skve](https://github.com/skve)! - Fixed dependency graph
+
+### Patch Changes
+
+- [`99b741d`](https://github.com/interfere-inc/interfere/commit/99b741d9cbc336d5194a4c36acd7c8afdad6d7ba) Thanks [@skve](https://github.com/skve)! - bump
+
+- [`bc3cdb3`](https://github.com/interfere-inc/interfere/commit/bc3cdb362c595217c1ffe70e462c1e994a3043b1) Thanks [@skve](https://github.com/skve)! - bump
+
+- [`6e791b6`](https://github.com/interfere-inc/interfere/commit/6e791b6e05151da43259bdb026b126949e2f6470) Thanks [@skve](https://github.com/skve)! - bump
+
+- [`6e791b6`](https://github.com/interfere-inc/interfere/commit/6e791b6e05151da43259bdb026b126949e2f6470) Thanks [@skve](https://github.com/skve)! - fix
+
+- [`2847cd7`](https://github.com/interfere-inc/interfere/commit/2847cd75cd9a067e6b265864f1ed01c01ffe8a22) Thanks [@skve](https://github.com/skve)! - Improvements, Native Next.js 16 support, and huge performance improvements.
+
+## 1.0.0-alpha.6
+
+### Major Changes
+
+- [`17fe701`](https://github.com/interfere-inc/interfere/commit/17fe701227f2a55644eb77b254888a5a0657036d) Thanks [@skve](https://github.com/skve)! - feat: release v1
+
+## 0.2.0-alpha.5
+
+### Patch Changes
+
+- bump
+
+## 0.2.0-alpha.4
+
+### Patch Changes
+
+- bump
+
+## 0.2.0-alpha.3
+
+### Patch Changes
+
+- fix
+
+## 0.2.0-alpha.2
+
+### Patch Changes
+
+- bump
+
+## 0.2.0-alpha.1
+
+### Patch Changes
+
+- Fix silent initialization issues
+
+## 0.1.0-alpha.32
+
+### Minor Changes
+
+- [`949b3e2`](https://github.com/interfere-inc/interfere/commit/949b3e27002091477e4fdbd37e6c77d6de4ff780) Thanks [@skve](https://github.com/skve)! - Fixed dependency graph
+
+## 0.0.1-alpha.31
+
+### Patch Changes
+
+- [`2847cd7`](https://github.com/interfere-inc/interfere/commit/2847cd75cd9a067e6b265864f1ed01c01ffe8a22) Thanks [@skve](https://github.com/skve)! - Improvements, Native Next.js 16 support, and huge performance improvements.

package/FUNCTIONS.md

@@ -0,0 +1,136 @@
+# Standalone Functions
+
+> [!NOTE]
+> This section is useful if you are using a bundler and targetting browsers and
+> runtimes where the size of an application affects performance and load times. 
+
+Every method in this SDK is also available as a standalone function. This
+alternative API is suitable when targetting the browser or serverless runtimes
+and using a bundler to build your application since all unused functionality
+will be tree-shaken away. This includes code for unused methods, Zod schemas,
+encoding helpers and response handlers. The result is dramatically smaller
+impact on the application's final bundle size which grows very slowly as you use
+more and more functionality from this SDK.
+
+Calling methods through the main SDK class remains a valid and generally more
+more ergonomic option. Standalone functions represent an optimisation for a
+specific category of applications.
+
+## Example
+
+```typescript
+import { InterfereCore } from "@interfere/sdk/core.js";
+import { ingestPost } from "@interfere/sdk/funcs/ingest-post.js";
+
+// Use `InterfereCore` for best tree-shaking performance.
+// You can create one instance of it to use across an application.
+const interfere = new InterfereCore();
+
+async function run() {
+  const res = await ingestPost(interfere, [
+    {
+      type: "replay_chunk",
+      buildId: "<id>",
+      clientTs: 870104,
+      environment: "development",
+      releaseId: "<id>",
+      runtime: "edge",
+      sessionId: "a2ba99cd-cfa7-4180-8531-8cf43498cb93",
+      uuid: "c6184cb5-7ebf-4da5-8951-879d34f73aaf",
+      v: 0,
+      payload: {
+        ts: 4133.68,
+        count: 5545.75,
+        events: [],
+      },
+    },
+    {
+      type: "error",
+      buildId: "<id>",
+      clientTs: 706130,
+      environment: "preview",
+      releaseId: "<id>",
+      runtime: "node",
+      sessionId: "eb8dc940-e4b3-4f0b-9d81-9d9129ee39d7",
+      uuid: "9c5d368e-bd79-4dcb-8e41-900825ef821a",
+      v: 0,
+      payload: {
+        exceptions: [
+          {
+            type: "<value>",
+            value: "<value>",
+            frames: [],
+          },
+        ],
+      },
+    },
+    {
+      type: "pageview",
+      buildId: "<id>",
+      clientTs: 505979,
+      environment: "preview",
+      releaseId: "<id>",
+      runtime: "edge",
+      sessionId: "4cc5eb79-5187-4fe2-9d83-d5da5974c1d6",
+      uuid: "cb48001e-3621-433b-af3c-476f1ec7ffe8",
+      v: 0,
+      payload: {
+        url: "https://same-statue.org/",
+      },
+    },
+  ]);
+  if (res.ok) {
+    const { value: result } = res;
+    console.log(result);
+  } else {
+    console.log("ingestPost failed:", res.error);
+  }
+}
+
+run();
+```
+
+## Result types
+
+Standalone functions differ from SDK methods in that they return a
+`Result<Value, Error>` type to capture _known errors_ and document them using
+the type system. By avoiding throwing errors, application code maintains clear
+control flow and error-handling become part of the regular flow of application
+code.
+
+> We use the term "known errors" because standalone functions, and JavaScript
+> code in general, can still throw unexpected errors such as `TypeError`s,
+> `RangeError`s and `DOMException`s. Exhaustively catching all errors may be
+> something this SDK addresses in the future. Nevertheless, there is still a lot
+> of benefit from capturing most errors and turning them into values.
+
+The second reason for this style of programming is because these functions will
+typically be used in front-end applications where exception throwing is
+sometimes discouraged or considered unidiomatic. React and similar ecosystems
+and libraries tend to promote this style of programming so that components
+render useful content under all states (loading, success, error and so on).
+
+The general pattern when calling standalone functions looks like this:
+
+```typescript
+import { Core } from "<sdk-package-name>";
+import { fetchSomething } from "<sdk-package-name>/funcs/fetchSomething.js";
+
+const client = new Core();
+
+async function run() {
+  const result = await fetchSomething(client, { id: "123" });
+  if (!result.ok) {
+    // You can throw the error or handle it. It's your choice now.
+    throw result.error;
+  }
+
+  console.log(result.value);
+}
+
+run();
+```
+
+Notably, `result.error` above will have an explicit type compared to a try-catch
+variation where the error in the catch block can only be of type `unknown` (or
+`any` depending on your TypeScript settings).

package/README.md

@@ -1,14 +1,11 @@
-# openapi
+# Interfere SDK
 
-Developer-friendly & type-safe Typescript SDK specifically catered to leverage *openapi* API.
-
-[![Built by Speakeasy](https://img.shields.io/badge/Built_by-SPEAKEASY-374151?style=for-the-badge&labelColor=f3f4f6)](https://www.speakeasy.com/?utm_source=openapi&utm_campaign=typescript)
 [![License: MIT](https://img.shields.io/badge/LICENSE_//_MIT-3b5bdb?style=for-the-badge&labelColor=eff6ff)](https://opensource.org/licenses/MIT)
 
 
 <br /><br />
 > [!IMPORTANT]
-> This SDK is not yet ready for production use. To complete setup please follow the steps outlined in your [workspace](https://app.speakeasy.com/org/interfere/api). Delete this section before > publishing to a package manager.
+> This SDK is not yet ready for external use, and only covers a very small subset of our API. We have plans to flesh out a fully built out public SDK in Q3 2026.
 
 <!-- Start Summary [summary] -->
 ## Summary
@@ -19,7 +16,7 @@ Interfere Collector API: Public ingestion API for Interfere SDKs
 <!-- Start Table of Contents [toc] -->
 ## Table of Contents
 <!-- $toc-max-depth=2 -->
-* [openapi](#openapi)
+* [Interfere SDK](#interfere-sdk)
   * [SDK Installation](#sdk-installation)
   * [Requirements](#requirements)
   * [SDK Example Usage](#sdk-example-usage)
@@ -33,7 +30,6 @@ Interfere Collector API: Public ingestion API for Interfere SDKs
   * [Debugging](#debugging)
 * [Development](#development)
   * [Maturity](#maturity)
-  * [Contributions](#contributions)
 
 <!-- End Table of Contents [toc] -->
 
@@ -71,7 +67,8 @@ yarn add <UNSET>
 ```
 
 > [!NOTE]
-> This package is published with CommonJS and ES Modules (ESM) support.
+> This package is published as an ES Module (ESM) only. For applications using
+> CommonJS, use `await import()` to import and use this package.
 <!-- End SDK Installation [installation] -->
 
 <!-- Start Requirements [requirements] -->
@@ -83,7 +80,9 @@ For supported JavaScript runtimes, please consult [RUNTIMES.md](RUNTIMES.md).
 <!-- Start SDK Example Usage [usage] -->
 ## SDK Example Usage
 
-### Example
+### Ingest a batch of events
+
+Send a batch of event envelopes (errors, pageviews, rage clicks, ...) to the collector.
 
 ```typescript
 import { Interfere } from "@interfere/sdk";
@@ -91,7 +90,58 @@ import { Interfere } from "@interfere/sdk";
 const interfere = new Interfere();
 
 async function run() {
-  const result = await interfere.health.get();
+  const result = await interfere.ingest.post([
+    {
+      type: "replay_chunk",
+      buildId: "<id>",
+      clientTs: 870104,
+      environment: "development",
+      releaseId: "<id>",
+      runtime: "edge",
+      sessionId: "a2ba99cd-cfa7-4180-8531-8cf43498cb93",
+      uuid: "c6184cb5-7ebf-4da5-8951-879d34f73aaf",
+      v: 0,
+      payload: {
+        ts: 4133.68,
+        count: 5545.75,
+        events: [],
+      },
+    },
+    {
+      type: "error",
+      buildId: "<id>",
+      clientTs: 706130,
+      environment: "preview",
+      releaseId: "<id>",
+      runtime: "node",
+      sessionId: "eb8dc940-e4b3-4f0b-9d81-9d9129ee39d7",
+      uuid: "9c5d368e-bd79-4dcb-8e41-900825ef821a",
+      v: 0,
+      payload: {
+        exceptions: [
+          {
+            type: "<value>",
+            value: "<value>",
+            frames: [],
+          },
+        ],
+      },
+    },
+    {
+      type: "pageview",
+      buildId: "<id>",
+      clientTs: 505979,
+      environment: "preview",
+      releaseId: "<id>",
+      runtime: "edge",
+      sessionId: "4cc5eb79-5187-4fe2-9d83-d5da5974c1d6",
+      uuid: "cb48001e-3621-433b-af3c-476f1ec7ffe8",
+      v: 0,
+      payload: {
+        url: "https://same-statue.org/",
+      },
+    },
+  ]);
 
   console.log(result);
 }
@@ -107,6 +157,10 @@ run();
 <details open>
 <summary>Available methods</summary>
 
+### [Config](docs/sdks/config/README.md)
+
+* [get](docs/sdks/config/README.md#get)
+
 ### [Health](docs/sdks/health/README.md)
 
 * [get](docs/sdks/health/README.md#get)
@@ -122,8 +176,8 @@ run();
 
 ### [Sessions](docs/sdks/sessions/README.md)
 
-* [identify](docs/sdks/sessions/README.md#identify)
 * [create](docs/sdks/sessions/README.md#create)
+* [identify](docs/sdks/sessions/README.md#identify)
 
 ### [SourceMaps](docs/sdks/sourcemaps/README.md)
 
@@ -152,6 +206,7 @@ To read more about standalone functions, check [FUNCTIONS.md](./FUNCTIONS.md).
 
 <summary>Available standalone functions</summary>
 
+- [`configGet`](docs/sdks/config/README.md#get)
 - [`healthGet`](docs/sdks/health/README.md#get)
 - [`ingestPost`](docs/sdks/ingest/README.md#post)
 - [`releasesCreate`](docs/sdks/releases/README.md#create)
@@ -190,11 +245,7 @@ async function run() {
     body: {
       files: [],
       metadata: {
-        sourceMapToGenerated: {
-          "key": "<value>",
-          "key1": "<value>",
-          "key2": "<value>",
-        },
+        sourceMapToGenerated: {},
         hashes: {},
       },
     },
@@ -273,18 +324,19 @@ run();
 
 [`InterfereHTTPError`](./src/models/errors/interfere-http-error.ts) is the base class for all HTTP error responses. It has the following properties:
 
-| Property            | Type       | Description                                            |
-| ------------------- | ---------- | ------------------------------------------------------ |
-| `error.message`     | `string`   | Error message                                          |
-| `error.statusCode`  | `number`   | HTTP response status code eg `404`                     |
-| `error.headers`     | `Headers`  | HTTP response headers                                  |
-| `error.body`        | `string`   | HTTP body. Can be empty string if no body is returned. |
-| `error.rawResponse` | `Response` | Raw HTTP response                                      |
+| Property            | Type       | Description                                                                             |
+| ------------------- | ---------- | --------------------------------------------------------------------------------------- |
+| `error.message`     | `string`   | Error message                                                                           |
+| `error.statusCode`  | `number`   | HTTP response status code eg `404`                                                      |
+| `error.headers`     | `Headers`  | HTTP response headers                                                                   |
+| `error.body`        | `string`   | HTTP body. Can be empty string if no body is returned.                                  |
+| `error.rawResponse` | `Response` | Raw HTTP response                                                                       |
+| `error.data$`       |            | Optional. Some errors may contain structured data. [See Error Classes](#error-classes). |
 
 ### Example
 ```typescript
 import { Interfere } from "@interfere/sdk";
-import { InterfereHTTPError } from "@interfere/sdk/models/errors/interfere-http-error.js.js";
+import * as errors from "@interfere/sdk/models/errors";
 
 const interfere = new Interfere();
 
@@ -294,11 +346,18 @@ async function run() {
 
     console.log(result);
   } catch (error) {
-    if (error instanceof InterfereHTTPError) {
+    // The base class for HTTP error responses
+    if (error instanceof errors.InterfereHTTPError) {
       console.log(error.message);
       console.log(error.statusCode);
       console.log(error.body);
       console.log(error.headers);
+
+      // Depending on the method different errors may be thrown
+      if (error instanceof errors.HealthError) {
+        console.log(error.data$.ok); // boolean
+        console.log(error.data$.message); // string
+      }
     }
   }
 }
@@ -308,10 +367,11 @@ run();
 ```
 
 ### Error Classes
-**Primary error:**
+**Primary errors:**
 * [`InterfereHTTPError`](./src/models/errors/interfere-http-error.ts): The base class for HTTP error responses.
+  * [`ErrorsProblem`](./src/models/errors/errors-problem.ts): Standard error envelope for 4XX / 5XX responses. *
 
-<details><summary>Less common errors (6)</summary>
+<details><summary>Less common errors (7)</summary>
 
 <br />
 
@@ -324,9 +384,12 @@ run();
 
 
 **Inherit from [`InterfereHTTPError`](./src/models/errors/interfere-http-error.ts)**:
+* [`HealthError`](./src/models/errors/health-error.ts): Response for status 500. Status code `500`. Applicable to 1 of 10 methods.*
 * [`ResponseValidationError`](./src/models/errors/response-validation-error.ts): Type mismatch between the data returned from the server and the structure expected by the SDK. See `error.rawValue` for the raw value and `error.pretty()` for a nicely formatted multi-line string.
 
 </details>
+
+\* Check [the method documentation](#available-resources-and-operations) to see if the error is applicable.
 <!-- End Error Handling [errors] -->
 
 <!-- Start Server Selection [server] -->
@@ -433,11 +496,4 @@ You can also enable a default debug logger by setting an environment variable `I
 
 This SDK is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage
 to a specific package version. This way, you can install the same version each time without breaking changes unless you are intentionally
-looking for the latest version.
-
-## Contributions
-
-While we value open-source contributions to this SDK, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. 
-We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release. 
-
-### SDK Created by [Speakeasy](https://www.speakeasy.com/?utm_source=openapi&utm_campaign=typescript)
+looking for the latest version.

package/RUNTIMES.md

@@ -0,0 +1,48 @@
+# Supported JavaScript runtimes
+
+This SDK is intended to be used in JavaScript runtimes that support ECMAScript 2020 or newer. The SDK uses the following features:
+
+- [Web Fetch API][web-fetch]
+- [Web Streams API][web-streams] and in particular `ReadableStream`
+- [Async iterables][async-iter] using `Symbol.asyncIterator`
+
+[web-fetch]: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
+[web-streams]: https://developer.mozilla.org/en-US/docs/Web/API/Streams_API
+[async-iter]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols
+
+Runtime environments that are explicitly supported are:
+
+- Evergreen browsers which include: Chrome, Safari, Edge, Firefox
+- Node.js active and maintenance LTS releases
+  - Currently, this is v18 and v20
+- Bun v1 and above
+- Deno v1.39
+  - Note that Deno does not currently have native support for streaming file uploads backed by the filesystem ([issue link][deno-file-streaming])
+
+[deno-file-streaming]: https://github.com/denoland/deno/issues/11018
+
+## Recommended TypeScript compiler options
+
+The following `tsconfig.json` options are recommended for projects using this
+SDK in order to get static type support for features like async iterables,
+streams and `fetch`-related APIs ([`for await...of`][for-await-of],
+[`AbortSignal`][abort-signal], [`Request`][request], [`Response`][response] and
+so on):
+
+[for-await-of]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of
+[abort-signal]: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
+[request]: https://developer.mozilla.org/en-US/docs/Web/API/Request
+[response]: https://developer.mozilla.org/en-US/docs/Web/API/Response
+
+```jsonc
+{
+  "compilerOptions": {
+    "target": "es2020", // or higher
+    "lib": ["es2020", "dom", "dom.iterable"]
+  }
+}
+```
+
+While `target` can be set to older ECMAScript versions, it may result in extra,
+unnecessary compatibility code being generated if you are not targeting old
+runtimes.

package/jsr.json

@@ -0,0 +1,27 @@
+
+
+{
+  "name": "@interfere/sdk",
+  "version": "8.1.5",
+  "exports": {
+    ".": "./src/index.ts",    
+    "./models/errors": "./src/models/errors/index.ts",    
+    "./models": "./src/models/index.ts",    
+    "./models/operations": "./src/models/operations/index.ts",
+    "./lib/config": "./src/lib/config.ts",
+    "./lib/http": "./src/lib/http.ts",
+    "./lib/retries": "./src/lib/retries.ts",
+    "./lib/sdks": "./src/lib/sdks.ts",
+    "./types": "./src/types/index.ts"
+  },
+  "publish": {
+    "include": [
+      "LICENSE",
+      "README.md",
+      "RUNTIMES.md",
+      "USAGE.md",
+      "jsr.json",
+      "src/**/*.ts"
+    ]
+  }
+}