Typed SDK & client

The @netscript/sdk is the typed client and data layer for NetScript: it turns an @orpc/contract into a discovered, type-safe service client, wraps each contract action in a cache-first query factory (KV-backed SWR), and bridges those into TanStack Query for islands. The contract object is the single source of truth — the same object the service implements is the one the client imports, so caller and server cannot drift.

alpha

What it is

The SDK is layered. L1 is the typed client: createServiceClient<Contract>() resolves a service URL from Aspire service discovery and returns a callable object whose method signatures are inferred from the contract. L2 wraps each contract action in a query factory (createQueryFactories) that runs through a shared KV-backed cache provider and exposes queryOptions/mutationOptions/clientKey/key/getCachedEntry per action. L3 is the defineServices() preset that builds clients, server query factories, and frontend query utils from one contract map. You consume the layer you need and can drop down without rewiring. See Contracts for the type-flow theory.

Learn → / Do →

Minimal example

A single lib/api-clients.ts is the spine of the data layer: build the typed client from a contract, then derive a query factory from { contract, client }. Every consumer — server loader or island — imports from here.

// apps/playground/lib/api-clients.ts
import { createServiceClient } from '@netscript/sdk/client';
import { createQueryFactories } from '@netscript/sdk/query';
import { ordersContract } from '@contracts';

// L1 — typed client. `serviceName` resolves a URL via Aspire discovery.
export const ordersClient = createServiceClient<typeof ordersContract>({
  contract: ordersContract,
  serviceName: 'orders',
});

// L2 — cache-first query factory bound to that client (KV-backed SWR).
export const api = createQueryFactories({
  orders: { contract: ordersContract, client: ordersClient },
});

// Direct typed call: `.list()` is fully inferred from the contract.
const recent = await ordersClient.list({ limit: 10 });

Key types first

The query factory is the heart of the data layer. Each contract action becomes an ActionMethod carrying the full cache-first surface — keys, prefetch, cached reads, and TanStack option helpers. These are the methods you call from a definePage loader and an island; reading them first explains the rest of the page.

Constructing the client & factory

The two L1/L2 constructors and their options. createServiceClient is the only call that touches discovery; createQueryFactories is pure wiring over { contract, client }.

The L3 alternative builds all three layers from one map: defineServices({ orders: { contract, serviceName: 'orders' } }) returns { clients, queryFactories, queryUtils } — the same L2 values, just composed in one call.

Service discovery & query client

serviceName is resolved at call time from Aspire-injected environment variables. The @netscript/sdk/discovery subpath exposes the resolvers directly when you need a raw URL, and @netscript/sdk/query-client provides the browser-side TanStack glue.

// routes/(dashboard)/orders/(_loaders)/orders-list.ts
import { api } from '@/lib/api-clients.ts';

// Cache-first: read the KV entry (with cachedAt) for SWR; fall back to a fetch.
export const loadOrders = async () => {
  const entry = await api.orders.list.getCachedEntry({ limit: 20 });
  if (entry) return entry; // serve cached; SDK reloads stale in the background
  return { data: await api.orders.list.queryOptions({ limit: 20 }).queryFn(), cachedAt: Date.now() };
};

// orders/(_islands)/OrdersQueryIsland.tsx
import { useQuery, useQueryClient } from '@netscript/fresh/query';
import { api } from '@/lib/api-clients.ts';

// Same contract action → same query key as the server loader, so the island
// hydrates from server state instead of refetching on mount.
const OrdersList = () => {
  const qc = useQueryClient();
  const orders = useQuery(api.orders.list.queryOptions({ limit: 20 }));
  // invalidate by prefix after a write:
  const refresh = () => qc.invalidateQueries({ queryKey: api.orders.list.clientKey() });
  return null; // render orders.data
};

// services/orders/src/routers/v1.ts — service-to-service call
import { safe, isDefinedError } from '@netscript/sdk/client';
import { usersClient } from '@/lib/api-clients.ts';

const [error, user, isDefined] = await safe(usersClient.getById({ id }));
if (error) {
  // narrow to a typed, contract-declared error
  if (isDefinedError(error)) return { code: error.code, status: error.status };
  throw error;
}

Production notes

Reference →

This hub is intentionally thin — the full generated API (client, query, query-client, cache, collections, discovery, streams, telemetry, ports) lives in the reference.

sdk