@koderlabs/tasks-sdk-react 0.1.0 → 0.1.1

package/README.md

@@ -1,9 +1,104 @@
-# Proprietary Software
+# @koderlabs/tasks-sdk-react
 
-KoderLabs proprietary. All rights reserved.
+> Runtime: browser DOM with React 18+. For Next.js App Router use `@koderlabs/tasks-sdk-nextjs/client` (which re-exports these). For RN see `@koderlabs/tasks-sdk-rn`.
 
-See the bundled `LICENSE` for terms. No grant of any rights, express or
-implied, is conferred by access to or possession of this package. A
-separate signed written licence from KoderLabs is required for any use.
+React adapter for the InstantTasks SDK. Provides `<InstantTasksProvider>`, the `useInstantTasks()` hook, a `useUser()` helper, and an `<ErrorBoundary>` class component.
+
+The provider initialises the core SDK at mount and exposes the client + any registered sub-clients (reporter, errors, network) via React context.
+
+## Install
+
+```bash
+pnpm add @koderlabs/tasks-sdk @koderlabs/tasks-sdk-react
+# plus the integrations you need:
+pnpm add @koderlabs/tasks-sdk-web-errors @koderlabs/tasks-sdk-web-network @koderlabs/tasks-sdk-web-reporter
+```
+
+## Usage
+
+```tsx
+import { InstantTasksProvider, useInstantTasks, ErrorBoundary } from '@koderlabs/tasks-sdk-react';
+import { errorsIntegration } from '@koderlabs/tasks-sdk-web-errors';
+import { networkIntegration } from '@koderlabs/tasks-sdk-web-network';
+import { reporterIntegration } from '@koderlabs/tasks-sdk-web-reporter';
+
+const sdkOptions = {
+  projectId: 'FE',
+  accessKey: import.meta.env.VITE_IT_ACCESS_KEY,
+  release: import.meta.env.VITE_APP_VERSION,
+  environment: import.meta.env.MODE,
+  integrations: [errorsIntegration(), networkIntegration(), reporterIntegration()],
+};
+
+export function App() {
+  return (
+    <InstantTasksProvider options={sdkOptions}>
+      <ErrorBoundary fallback={(err) => <div>Crashed: {err.message}</div>}>
+        <Routes />
+      </ErrorBoundary>
+    </InstantTasksProvider>
+  );
+}
+
+function ReportBugBtn() {
+  const { reporter } = useInstantTasks();
+  return <button onClick={() => reporter?.show()}>Report a bug</button>;
+}
+```
+
+## API
+
+### `<InstantTasksProvider options={InitOptions}>`
+
+Initialises the SDK at mount and tears it down on unmount.
+
+- **Browser mount**: client is created via a `useState` lazy initialiser so consumers in the same paint see a real `Client` (no null window).
+- **SSR / RSC**: lazy init returns `null` (no `window`); a browser-only `useEffect` then initialises and surfaces the client via state.
+- **StrictMode double-mount (dev)**: `init()` is idempotent and tears down the prior client on the second mount.
+- Re-init on `options` change is **not** supported. Memoize upstream or use `setUser` / `setCustomData` for runtime updates.
+
+### `useInstantTasks(): UseInstantTasksResult`
+
+| Field | Type | Notes |
+|---|---|---|
+| `client` | `Client \| null` | Core SDK client. |
+| `reporter` | `any \| null` | From `@koderlabs/tasks-sdk-web-reporter` integration. |
+| `widget` | `any \| null` | **Deprecated alias** of `reporter`. Will be removed in v1. |
+| `errors` | `any \| null` | From `@koderlabs/tasks-sdk-web-errors` integration. |
+| `network` | `any \| null` | From `@koderlabs/tasks-sdk-web-network` integration. |
+
+Strongly-typed sub-clients ship in Phase E. For now consumers cast as needed.
+
+### `useUser()`
+
+Convenience hook for setting the current user on the client. See `src/useUser.ts` for signature.
+
+### `<ErrorBoundary fallback={ReactNode | (err) => ReactNode} client?={…}>`
+
+Sentry-style class boundary. On `componentDidCatch` it calls `client.errors.notify(err, { componentStack })` if the errors sub-client is registered, otherwise falls back to `client.send(...)`. Renders `fallback` when caught.
+
+Must be a class component — React 18/19 has no functional equivalent for `componentDidCatch`.
+
+### Other exports
+
+- `InstantTasksContext`, `InstantTasksContextValue` — for advanced custom providers.
+- `InstantTasksProviderProps`, `ErrorBoundaryProps`, `UseInstantTasksResult` — types.
+
+## Caveats
+
+- `<InstantTasksProvider>` swallows `init()` errors (bad endpoint, malformed key) — the host app continues to render without telemetry. Use `debug: true` on `InitOptions` to surface them.
+- `options` are read once. To change the user/customData at runtime, get the `client` from the hook and call its mutators.
+- `ErrorBoundary` will not catch errors in event handlers, async code, SSR, or its own children's `componentDidMount` after the boundary itself unmounted — standard React boundary limitations.
+- `useInstantTasks().widget` is deprecated. Migrate to `.reporter`. See `docs/sdk/migration-v1.md`.
+
+---
+
+## Suite overview
+
+Full SDK suite map + platform availability matrix: [docs/sdk/overview.md](https://github.com/jawaidgadiwala/instant-tasks/blob/main/docs/sdk/overview.md).
+
+## License
+
+KoderLabs proprietary. See [`LICENSE`](./LICENSE) for terms. Use of this package requires a separate signed written agreement with KoderLabs; access alone confers no rights.
 
 Licensing inquiries: jawaidgadiwala@gmail.com

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koderlabs/tasks-sdk-react",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "React Provider + hooks for the InstantTasks SDK.",
   "keywords": [
     "instanttasks",
@@ -39,7 +39,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@koderlabs/tasks-sdk": "0.1.0"
+    "@koderlabs/tasks-sdk": "0.1.1"
   },
   "peerDependencies": {
     "react": "^18 || ^19",
@@ -61,7 +61,7 @@
     "node": ">=20"
   },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
   "scripts": {
     "build": "tsup",