@cskn/sdk

The one SDK a mini app uses to talk to the cskn platform and the native shell.

@cskn/sdk has three layers. You can use any of them on its own.

App data

Synchronous accessors for what the host injected into window.cskn.

Platform API

An authenticated HTTP client for api.csknapps.xyz and TanStack Query hooks for the common endpoints.

Native bridge

Camera, storage, notifications, passkeys and more, through the shell’s bridge.

Setup

The API hooks use TanStack Query, so the app needs a QueryClientProvider. Then call useBridgeAuth once at the root.

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { useBridgeAuth } from '@cskn/sdk';

const queryClient = new QueryClient();

export function Root() {
  return (
    <QueryClientProvider client={queryClient}>
      <App />
    </QueryClientProvider>
  );
}

function App() {
  const { isReady } = useBridgeAuth();
  if (!isReady) return null;
  return <Routes />;
}

Conventions

• Hooks and functions come in pairs. Every native feature has plain functions (capturePhoto, storageGet) and a React hook (useCamera, useStorage). The hooks are thin wrappers, so use the functions anywhere outside a component.
• Results, not exceptions. Native calls resolve with { cancelled } or { error } instead of throwing. Check them before reading the payload.
• appSlug defaults to the current app. Hooks that take an app slug (widgets, settings, themes) fall back to window.cskn.app.slug, so you rarely pass one.

Full example

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { useBridgeAuth, useUser, useAppControl, useHaptics } from '@cskn/sdk';

const queryClient = new QueryClient();

export default function Root() {
  return (
    <QueryClientProvider client={queryClient}>
      <MiniApp />
    </QueryClientProvider>
  );
}

function MiniApp() {
  const { isReady, token } = useBridgeAuth();
  const { data: user } = useUser({ enabled: isReady && !!token });
  const { closeApp } = useAppControl();
  const haptics = useHaptics();

  if (!isReady) return <p>Loading…</p>;

  return (
    <main>
      <h1>Hello {user?.name}</h1>
      <button
        onClick={() => {
          haptics.impact('light');
          closeApp();
        }}
      >
        Close
      </button>
    </main>
  );
}