> ## Documentation Index
> Fetch the complete documentation index at: https://docs.motioness.com/llms.txt
> Use this file to discover all available pages before exploring further.

# @motioness/proxy-client

TypeScript helpers, web component, and React binding for proxy URLs.

# @motioness/proxy-client

The official client SDK. Three exports for three layers of integration. **Most apps should reach for the [React component](/sdks/react) first** — it ships with the full effect set (hover, lazy, callbacks, SSR). Drop down to the web component or `buildProxyUrl()` only when you need to.

- **`<MotionessImg>`** — React binding. Hover effects, lazy loading, signed-URL props, SSR-safe. **Recommended.**
- **`<motioness-img>`** — web component (custom element). Same effects as the React binding without React. Drops into any HTML page.
- **`buildProxyUrl()`** — pure-function URL builder. No DOM, no React. For OG cards, RSS, server-side rendering of `<video>` directly.

## Install

```bash
npm install @motioness/proxy-client
```

Peer deps: `react` >= 18 and `react-dom` >= 18 (only for the React entry).

## `buildProxyUrl(opts)`

The lowest-level entry. Returns `{ mp4, jpg }`:

```ts
import { buildProxyUrl } from '@motioness/proxy-client';

const urls = buildProxyUrl({
  origin: 'https://motioness.com',
  projectKey: 'pk_abc',
  src: 'https://cdn.acme.com/hero.png',
  motion: 'medium',
  durSeconds: 4,
});

urls.mp4; // → https://motioness.com/v1/pk_abc/cdn.acme.com/hero.png.mp4?motion=medium&dur=4
urls.jpg; // → https://motioness.com/v1/pk_abc/cdn.acme.com/hero.png.jpg
```

### Options

| Option | Type | Default | Description |
|---|---|---|---|
| `origin` | string | required | Usually `https://motioness.com` |
| `projectKey` | string | required | Your `pk_…` |
| `src` | string | required | Full source URL with scheme |
| `motion` | `'subtle' \| 'medium' \| 'kinetic'` | project default | Motion intensity |
| `durSeconds` | number | project default | Output length, clamped 2-8 |
| `mode` | `'loop' \| 'animate-in' \| 'animate-on-hover'` | project default | Playback shape |
| `prompt` | string | — | Override the brand-aware vision prompt (≤500 chars) |
| `seed` | number | — | Deterministic seed |
| `aspect` | `'1:1' \| '16:9' \| '9:16' \| 'preserve'` | `preserve` | Output framing |
| `idempotencyKey` | string | — | Force a distinct asset from the same source |
| `waitMs` | number | 0 | Long-poll up to N ms before falling back to 202 |
| `signature` | string | — | HMAC sig for signed mode |
| `exp` | number | — | Unix seconds expiry for signed mode |

When `signature` is set, `src` is base64url-encoded into the path. Otherwise the scheme is stripped and the source URL is in the path verbatim. See [signed URLs](/guides/signed-urls).

## `<motioness-img>` web component

Self-contained custom element. Drop it in any HTML page:

```html
<script type="module" src="https://motioness.com/proxy-client/element.js"></script>

<motioness-img
  project-key="pk_abc"
  src="https://cdn.acme.com/hero.png"
  motion="medium"
  dur-seconds="4"
  mode="loop"
  style="width: 100%; max-width: 800px;"
/>
```

Renders `<video>` with poster, `autoplay muted loop playsinline` defaults. All the `buildProxyUrl` options are exposed as kebab-case attributes (`project-key`, `dur-seconds`, `wait-ms`, `idempotency-key`).

### Mode behavior

| Mode | Element behavior |
|---|---|
| `loop` | Autoplays, loops. |
| `animate-in` | Plays once on entry. Sets `loop=false`. |
| `animate-on-hover` | Loads metadata only. Plays on `mouseenter`, pauses + resets on `mouseleave`. |

### Lazy loading

```html
<motioness-img loading="lazy" ... />
```

Defers loading the mp4 until the element scrolls into view (uses `IntersectionObserver`). Poster jpg loads eagerly.

## `<MotionessImg>` React binding

```tsx
import { MotionessImg } from '@motioness/proxy-client/react';

export function Hero() {
  return (
    <MotionessImg
      projectKey="pk_abc"
      src="https://cdn.acme.com/hero.png"
      motion="kinetic"
      mode="loop"
      durSeconds={5}
      style={{ width: '100%', borderRadius: 12 }}
      onReady={(el) => console.log('mp4 loaded', el.duration)}
      onError={(err) => console.error(err)}
    />
  );
}
```

Same props as the web component (camelCase). Adds `onReady` and `onError` callbacks.

The React binding lazily registers the custom element on mount, so you don't need a separate `<script>` tag.

## TypeScript

All entries ship `.d.ts`. Import types directly:

```ts
import type { Motion, Mode, Aspect, ProxyUrls } from '@motioness/proxy-client';
import type { BuildUrlOptions } from '@motioness/proxy-client';
```

## Bundle size

| Entry | Min+gz |
|---|---|
| `@motioness/proxy-client` (buildProxyUrl only) | ~600B |
| `@motioness/proxy-client/element` | ~2KB |
| `@motioness/proxy-client/react` | ~500B + element |

No external dependencies (besides peer-deps for the React entry).