Merge pull request #23 from panoratech/speakeasy-sdk-regen-1723249483

chore: 🐝 Update SDK - Generate 0.11.0

.speakeasy/gen.yaml

@@ -12,7 +12,7 @@ generation:
   auth:
     oAuth2ClientCredentialsEnabled: false
 typescript:
-  version: 0.10.0
+  version: 0.11.0
   additionalDependencies:
     dependencies: {}
     devDependencies: {}

.speakeasy/workflow.lock

@@ -1,20 +1,20 @@
-speakeasyVersion: 1.358.0
+speakeasyVersion: 1.366.0
 sources:
     panora-open-api-swagger:
         sourceNamespace: panora-open-api-swagger
-        sourceRevisionDigest: sha256:6818cdf26228c94e606837084202e38ff67aea4e204360cc02d977be55f6dea0
-        sourceBlobDigest: sha256:5501b8335575db2489337145909ab158a161f6e2f66bcda01afa320fb5f34c9d
+        sourceRevisionDigest: sha256:0db8ab701ce7dd81f348b36d0adbdc7d7ad5708b004bed009ee414f0c796fc6b
+        sourceBlobDigest: sha256:132b52765c782c8d45dc35538b7792f878d777d3ad53af0272e423f5dddcf0b5
         tags:
             - latest
             - main
 targets:
     my-first-target:
         source: panora-open-api-swagger
         sourceNamespace: panora-open-api-swagger
-        sourceRevisionDigest: sha256:6818cdf26228c94e606837084202e38ff67aea4e204360cc02d977be55f6dea0
-        sourceBlobDigest: sha256:5501b8335575db2489337145909ab158a161f6e2f66bcda01afa320fb5f34c9d
+        sourceRevisionDigest: sha256:0db8ab701ce7dd81f348b36d0adbdc7d7ad5708b004bed009ee414f0c796fc6b
+        sourceBlobDigest: sha256:132b52765c782c8d45dc35538b7792f878d777d3ad53af0272e423f5dddcf0b5
         codeSamplesNamespace: code-samples-typescript-my-first-target
-        codeSamplesRevisionDigest: sha256:b7813a9ac263acadc0927b671acac9c96dbabc57fa2f00ca1e7cc3dfdc6b02d7
+        codeSamplesRevisionDigest: sha256:ac7e50977ee0f9d2a68f0b9e0d3793f7cbc75d9f1d380a72bab1f50549ca0077
         outLocation: /github/workspace/repo
 workflow:
     workflowVersion: 1.0.0

FUNCTIONS.md

@@ -0,0 +1,104 @@
+# 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 { PanoraCore } from "@panora/sdk/core.js";
+import { hello } from "@panora/sdk/funcs/hello.js";
+import { SDKValidationError } from "@panora/sdk/models/errors/sdkvalidationerror.js";
+
+// Use `PanoraCore` for best tree-shaking performance.
+// You can create one instance of it to use across an application.
+const panora = new PanoraCore({
+  apiKey: "<YOUR_API_KEY_HERE>",
+});
+
+async function run() {
+  const res = await hello(panora);
+
+  switch (true) {
+    case res.ok:
+      // The success case will be handled outside of the switch block
+      break;
+    case res.error instanceof SDKValidationError:
+      // Pretty-print validation errors.
+      return console.log(res.error.pretty());
+    case res.error instanceof Error:
+      return console.log(res.error);
+    default:
+      // TypeScript's type checking will fail on the following line if the above
+      // cases were not exhaustive.
+      res.error satisfies never;
+      throw new Error("Assertion failed: expected error checks to be exhaustive: " + res.error);
+  }
+
+
+  const { value: result } = res;
+
+  // Handle the result
+  console.log(result)
+}
+
+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).