# The SDK

> createStorewareApp handles webhooks, installs, admin sessions and API clients in one place.

Source: https://storeware.ai/docs/sdk

> **Early access.** The CLI and the SDK are not on npm yet, so the commands below do not run for everyone. To build an app now, write to https://storeware.ai/contact.

```bash
npm install @storeware/plugin-sdk
```

## One object

```ts
import { createStorewareApp, kvInstallationStore } from '@storeware/plugin-sdk';

const storeware = createStorewareApp({
  clientId: env.STOREWARE_CLIENT_ID,
  clientSecret: env.STOREWARE_CLIENT_SECRET,
  installations: kvInstallationStore(env.INSTALLATIONS),
});

storeware.webhooks.on('order.paid.v1', async (event) => {
  const client = await storeware.clientFor(event.storeId);
  // ...
});
```

- `webhooks.handle(request)` verifies each delivery with the secret of the shop it names, finishes installs from their grant, and dispatches.
- `authenticateAdmin(request)` proves the person looking at your home or panel, from its session token, and trades the first one for the install.
- `verifyRequest(request, kind)` does the same for tool, knowledge and block calls.
- `clientFor(storeId)` is an API client whose tokens rotate into your store by themselves.

## Anywhere

Every handler takes a fetch `Request` and returns a `Response`, and signing uses WebCrypto, so the SDK runs on Workers, Next route handlers, Hono, Bun, Deno and Node. For Express or `node:http`:

```ts
import { toNodeListener } from '@storeware/plugin-sdk/node';

app.post('/webhooks', toNodeListener((request) => storeware.webhooks.handle(request)));
```

Mount it before any body parser.

## Hosted by Storeware

For an app [Storeware hosts](https://storeware.ai/docs/build-apps/hosting), `createHostedApp(env)` returns the same object, built on what Storeware hands your code instead of a client secret and a store:

```ts
import { createHostedApp } from '@storeware/plugin-sdk';

const storeware = createHostedApp(env);
```

Swap it for `createStorewareApp` to move the app to a server of your own, and back.

## Testing

`@storeware/plugin-sdk/testing` signs requests and mints sessions exactly as Storeware does, so a handler that passes your tests verifies real traffic.

```ts
import { signedDelivery } from '@storeware/plugin-sdk/testing';

const request = await signedDelivery({ secret, event: 'order.paid.v1', storeId });
```

## Reference

Every export, module by module, read from the SDK's own source.

- [createStorewareApp](https://storeware.ai/docs/sdk/app): One object for webhooks, installs, admin sessions and API clients.
- [createHostedApp](https://storeware.ai/docs/sdk/hosted): The same object, for an app Storeware hosts, with its installations and data.
- [Verifying requests](https://storeware.ai/docs/sdk/webhooks): Check the signature on every call Storeware makes to your app.
- [API client](https://storeware.ai/docs/sdk/client): Call the API for one shop, with tokens that refresh themselves.
- [Testing](https://storeware.ai/docs/sdk/testing): Sign requests and mint sessions for your tests.