@openrouter/sdk 0.0.0-beta.0

package/.devcontainer/README.md

@@ -0,0 +1,30 @@
+
+> **Remember to shutdown a GitHub Codespace when it is not in use!**
+
+# Dev Containers Quick Start
+
+The default location for usage snippets is the `samples` directory.
+
+## Running a Usage Sample
+
+A sample usage example has been provided in a `root.ts` file. As you work with the SDK, it's expected that you will modify these samples to fit your needs. To execute this particular snippet, use the command below.
+
+```
+ts-node root.ts
+```
+
+## Generating Additional Usage Samples
+
+The speakeasy CLI allows you to generate more usage snippets. Here's how:
+
+- To generate a sample for a specific operation by providing an operation ID, use:
+
+```
+speakeasy generate usage -s .speakeasy/out.openapi.yaml -l typescript -i {INPUT_OPERATION_ID} -o ./samples
+```
+
+- To generate samples for an entire namespace (like a tag or group name), use:
+
+```
+speakeasy generate usage -s .speakeasy/out.openapi.yaml -l typescript -n {INPUT_TAG_NAME} -o ./samples
+```

package/.devcontainer/devcontainer.json

@@ -0,0 +1,45 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/images/tree/main/src/typescript-node
+{
+    "name": "TypeScript",
+    "image": "mcr.microsoft.com/devcontainers/typescript-node:1-20-bullseye",
+    // Features to add to the dev container. More info: https://containers.dev/features.
+    // "features": {},
+    // Use 'forwardPorts' to make a list of ports inside the container available locally.
+    // "forwardPorts": [],
+    // Use 'postCreateCommand' to run commands after the container is created.
+    "postCreateCommand": "sudo chmod +x ./.devcontainer/setup.sh && ./.devcontainer/setup.sh",
+    "customizations": {
+        "vscode": {
+            "extensions": [
+                "ms-vscode.vscode-typescript-tslint-plugin",
+                "esbenp.prettier-vscode",
+                "github.vscode-pull-request-github"
+            ],
+            "settings": {
+                "files.eol": "\n",
+                "editor.formatOnSave": true,
+                "typescript.tsc.autoDetect": "on",
+                "typescript.updateImportsOnFileMove.enabled": "always",
+                "typescript.preferences.importModuleSpecifier": "relative",
+                "[typescript]": {
+                    "editor.codeActionsOnSave": {
+                        "source.organizeImports": true
+                    }
+                },
+                "[typescriptreact]": {
+                    "editor.codeActionsOnSave": {
+                        "source.organizeImports": true
+                    }
+                }
+            }
+        },
+        "codespaces": {
+            "openFiles": [
+                ".devcontainer/README.md"
+            ]
+        }
+    }
+    // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
+    // "remoteUser": "root"
+}

package/FUNCTIONS.md

@@ -0,0 +1,89 @@
+# 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 { OpenRouterCore } from "@openrouter/sdk/core.js";
+import { getCredits } from "@openrouter/sdk/funcs/getCredits.js";
+
+// Use `OpenRouterCore` for best tree-shaking performance.
+// You can create one instance of it to use across an application.
+const openRouter = new OpenRouterCore({
+  security: {
+    apiKeyAuth: process.env["OPENROUTER_API_KEY_AUTH"] ?? "",
+  },
+});
+
+async function run() {
+  const res = await getCredits(openRouter);
+  if (res.ok) {
+    const { value: result } = res;
+    console.log(result);
+  } else {
+    console.log("getCredits 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/REACT_QUERY.md

@@ -0,0 +1,302 @@
+# React hooks
+
+This SDK provides React hooks and utilies for making queries and mutations that
+can take the pain out of building front-end applications for the web or React
+Native.
+
+They are built as a thin wrapper around [TanStack Query for React v5][rq], a
+powerful, asynchronous state management library. A good understanding of that
+library will be very helpful while using them. In addition to hooks, there are
+several helper functions that can be used for cache management and data fetching
+during server-rendering and in React Server Components.
+
+## Getting started
+
+To get started using React hooks, you will need to inject TanStack query and an
+SDK instance into your application. Typically, this will be done high up in
+your React app at the root or layout component. For example:
+
+```tsx
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { OpenRouterCore } from "@openrouter/sdk";
+import { OpenRouterProvider } from "@openrouter/sdk/react-query";
+
+const queryClient = new QueryClient();
+const openRouter = new OpenRouterCore({
+  security: {
+    apiKeyAuth: process.env["OPENROUTER_API_KEY_AUTH"] ?? "",
+  },
+});
+
+// Retries are handled by the underlying SDK.
+queryClient.setQueryDefaults(["@openrouter/sdk"], { retry: false });
+queryClient.setMutationDefaults(["@openrouter/sdk"], { retry: false });
+
+export function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <OpenRouterProvider client={openRouter}> 
+        {/* Your app logic starts here */}
+      </OpenRouterProvider>
+    </QueryClientProvider>
+  );
+}
+```
+
+## Queries
+
+Query hooks are the basic building block for fetching data. In addition to
+request data, they take the same options as the [`useQuery` hook][use-query]
+from TanStack Query.
+
+[use-query]: https://tanstack.com/query/v5/docs/framework/react/reference/useQuery
+
+```tsx
+import { useGetCredits } from "@openrouter/sdk/react-query/getCredits.js";
+
+export function Example() {
+  const { data, error, status } = useGetCredits();
+
+  // Render the UI here...
+}
+``` 
+
+### Query timeouts and retries
+
+Since the underlying SDK handles request timeouts and retries, there are a few
+more options provided by the query hooks to control these behaviors.
+
+```tsx
+import { useState } from "react";
+import { useGetCredits } from "@openrouter/sdk/react-query/getCredits.js";
+
+export function ExampleWithOptions() {
+  const [enabled, setEnabled] = useState(true);
+  const { data, error, status } = useGetCredits(
+    {
+      // TanStack Query options:
+      enabled,
+      staleTime: 60 * 1000, // 1 minute
+      gcTime: 5 * 60 * 1000, // 5 minutes
+
+      // Request options for the underlying API call:
+      timeoutMs: 1000,
+      retryCodes: ["5XX"],
+      retries: {
+        strategy: "backoff",
+        backoff: {
+          initialInterval: 500,
+          maxInterval: 10 * 1000, // 10 seconds
+          exponent: 1.5,
+          maxElapsedTime: 60 * 1000, // 1 minute
+        },
+      },
+    }
+  );
+
+  // Render the UI here...
+}
+```
+
+
+## Mutations
+
+Operations that can have side-effects in this SDK are exposed as mutation hooks.
+These can be integrated into HTML forms to submit data to the API. They also
+take the same options as the [`useMutation` hook][use-mutation] from TanStack
+Query.
+
+[use-mutation]: https://tanstack.com/query/v5/docs/framework/react/reference/useMutation
+
+```tsx
+import { usePostCreditsCoinbaseMutation } from "@openrouter/sdk/react-query/postCreditsCoinbase.js";
+
+export function Example() {
+  const { mutate, status } = usePostCreditsCoinbaseMutation();
+
+  return (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault();
+
+        // Read form data here...
+
+        mutate();
+      }}
+    >
+      {/* Form fields go here... */} 
+      <button type="submit" disabled={status === "pending"}>Submit</button>
+    </form>
+  );
+}
+``` 
+
+### Mutation timeouts and retries
+
+Since the underlying SDK handles request timeouts and retries, there are a few
+more options provided by the mutation hooks to control these behaviors.
+
+```tsx
+import { usePostCreditsCoinbaseMutation } from "@openrouter/sdk/react-query/postCreditsCoinbase.js";
+
+export function ExampleWithOptions() {
+  const { mutate, status } = usePostCreditsCoinbaseMutation({
+    // TanStack Query options:
+    networkMode: "online",
+    gcTime: 5 * 60 * 1000, // 5 minutes
+
+    // Request options for the underlying API call:
+    timeoutMs: 1000,
+    retryCodes: ["5XX"],
+    retries: {
+      strategy: "backoff",
+      backoff: {
+        initialInterval: 500,
+        maxInterval: 10 * 1000, // 10 seconds
+        exponent: 1.5,
+        maxElapsedTime: 60 * 1000, // 1 minute
+      },
+    },
+  });
+
+  // Render the UI here...
+}
+```
+
+
+## Cache invalidation
+
+In many instances, triggering a mutation hook requires invalidating specific
+query data currently residing in the TanStack Query's cache. Alongside every
+query hook there are two functions that help invalidate cached data:
+
+```tsx
+import { useQueryClient } from "@tanstack/react-query";
+import { invalidateGetCredits, invalidateAllGetCredits } from "@openrouter/sdk/react-query/getCredits.js";
+// Replace this with a real mutation
+import { useExampleMutation } from "@openrouter/sdk/react-query/example.js";
+
+export function Example() {
+  const { queryClient } = useQueryClient();
+  const { mutate, status } = useExampleMutation();
+
+  return (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault();
+
+        const formData = new FormData(e.target);
+
+        mutate(formData, {
+          onSuccess: () => {
+            // Invalidate a single cache entry:
+            invalidateGetCredits(queryClient, /* ... arguments ... */);
+            // OR, invalidate all cache entries for the query targets:
+            invalidateAllGetCredits(queryClient);
+          },
+        });
+      }}
+    >
+      {/* Form fields go here... */} 
+
+      <button type="submit" disabled={status === "pending"}>Submit</button>
+    </form>
+  );
+}
+```
+
+
+## Integration with React Suspense
+
+TanStack Query predates React Suspense and out of the box it does a great job at
+exposing the lifecycle of asynchronous tasks. However, if you are already using
+Suspense in your app, the default hooks will not trigger suspense boundaries.
+This is why the library and, by extension, this SDK also provide equivalent
+hooks that integrate neatly with React Suspense.
+
+```tsx
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { ErrorBoundary } from "react-error-boundary";
+
+import { OpenRouterCore } from "@openrouter/sdk";
+import { OpenRouterProvider } from "@openrouter/sdk/react-query";
+import { useGetCreditsSuspense } from "@openrouter/sdk/react-query/getCredits.js";
+
+const queryClient = new QueryClient();
+const openRouter = new OpenRouterCore({
+  security: {
+    apiKeyAuth: process.env["OPENROUTER_API_KEY_AUTH"] ?? "",
+  },
+});
+
+export function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <OpenRouterProvider client={openRouter}> 
+        <QueryErrorResetBoundary>
+          {({ reset }) => (
+            <ErrorBoundary
+              fallbackRender={({ error, resetErrorBoundary }) => (
+                <div>
+                  There was an error!{' '}
+                  <Button onClick={() => resetErrorBoundary()}>Try again</Button>
+                  <pre>{error.message}</pre>
+                </div>
+              )}
+              onReset={reset}
+            >
+              <React.Suspense fallback={<h1>Loading...</h1>}>
+                <Example />
+              </React.Suspense>
+            </ErrorBoundary>
+          )}
+        </QueryErrorResetBoundary>
+      </OpenRouterProvider>
+    </QueryClientProvider>
+  );
+}
+
+function Example() {
+  const { data } = useGetCreditsSuspense();
+
+  // Render the UI here...
+}
+```
+
+
+## Server-rendering and React Server Components
+
+Query hooks are also side-loaded with prefetch helper functions. These functions
+can be used to fetch data from the API during server-rendering and in React
+Server Components so that it can be available immediately on page load to any
+components that use the corresponding hooks:
+```tsx
+import {
+  dehydrate,
+  HydrationBoundary,
+  QueryClient,
+} from "@tanstack/react-query";
+import { OpenRouterCore } from "@openrouter/sdk";
+import { prefetchGetCredits } from "@openrouter/sdk/react-query/getCredits.js";
+
+export default async function Page() {
+  const queryClient = new QueryClient();
+  const openRouter = new OpenRouterCore({
+    security: {
+      apiKeyAuth: process.env["OPENROUTER_API_KEY_AUTH"] ?? "",
+    },
+  });
+
+  await prefetchGetCredits(openRouter);
+
+  return (
+    // HydrationBoundary is a Client Component, so hydration will happen there.
+    <HydrationBoundary state={dehydrate(queryClient)}>
+      {/* Client components under this point will also have data on page load. */}
+    </HydrationBoundary>
+  );
+}
+```
+
+
+[rq]: https://tanstack.com/query/v5/docs/framework/react/overview