Typed SDK & client

Declare a contract action once and everything the caller needs — the typed method, the query key, the cache entry, the TanStack options — is derived from it, in one import.

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.

beta

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.

Declare once, derived everywhere

The classic data-layer tax is the hand-rolled fetch wrapper: a lib/api.ts full of fetch() calls whose request and response types are re-typed by hand from whatever the server currently returns. Every server change costs a second edit in the wrapper, a third in the query keys, and whichever one is forgotten becomes a runtime bug. For an AI agent working the codebase the tax is worse — each of those copies is a separate turn, and a stale one is a wrong answer the agent cannot see until runtime.

The SDK collapses those copies into one declaration. tRPC made this move famous for TypeScript APIs — declare a procedure on the server and the client's types follow, "end-to-end typesafe." NetScript keeps that declare-once property and shifts where the declaration lives: not inside server code, but in a standalone, versioned contract package that the server, the client, and the OpenAPI/Scalar surface all import. And the derivation goes further than method types — from one contract action the factory derives the server KV cache key (key()), the client TanStack key (clientKey()), the queryOptions/mutationOptions helpers, and the SWR cache reads. One edit to the contract updates the client, the docs surface, and the query layer together — there is no separate turn to keep them in sync.

This is how a production chat application built on NetScript wires its dashboard: the typed client is built straight off the contract type, so a route added to the contract shows up on the client already typed. The mechanics of each layer are below; the type-flow theory is in Contracts.

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