@netscript/sdk

Service discovery, oRPC clients, and cache-backed query factories for NetScript. This page is written against the package's public surface reported by deno doc. For the full index of packages and plugins return to the reference overview.

The root entrypoint (@netscript/sdk) is the high-level composition entry for service-aware applications: it re-exports the client, query, query-client, discovery, telemetry, and OpenAPI surfaces and adds the defineServices() preset. It does not export the server cache engine or install a cache provider at import time. A single defineServices() call wires the whole typed stack — service clients, cache-aware query factories, and query utils — from one service map, so a component imports ready-to-use queryOptions() / mutationOptions() instead of hand-writing fetch wrappers. Focused sub-path exports carry the same values for narrow imports — see Sub-path exports.

Composition preset (defineServices)

These symbols are available from the root export and the focused, browser-safe @netscript/sdk/presets entry.

Service clients (@netscript/sdk/client)

Prefer the named discriminants: check result.isSuccess first, then result.isDefined on the failure before reading contract error codes and data. See Safe error narrowing for a service-client example. isDefinedError preserves defined members of an already typed error union; it does not infer contract errors from an arbitrary unknown value.

Tuple destructuring remains supported: const [error, data, isDefined, isSuccess] = await safe(promise). Both forms describe the same result. A bare promise without contract error typing has no statically reachable defined-error arm; see Bare promises and the defined-error arm.

Client contributions (SdkClientContribution)

CreateServiceClientOptions.contributions accepts an explicit literal tuple of request contributions. Tuple type inference projects the combined context declared across all contributions onto the per-call client context.

Every SdkClientContribution descriptor contains six required fields:

• protocol: Protocol version discriminator ({ family: 'netscript.sdk-client', major: 1 }).
• id: Globally unique contribution identifier (${string}:${string}).
• context: Runtime declaration mapping owned context keys to 'required' or 'optional'.
• headerKeys: Readonly array of exclusive lower-case HTTP request-header names owned by this contribution.
• responseCache: Response-cache policy declaration ({ mode: 'invariant' }, { mode: 'partitioned', partition: ... }, or { mode: 'direct-only' }).
• prepare: Synchronous or async hook returning a header patch ({ headers?: Record<string, string> }) for one logical request epoch.

import { oc } from '@orpc/contract';
import { createServiceClient, defineSdkClientContribution } from '@netscript/sdk/client';
import { z } from 'zod';

const contract = {
  echo: oc
    .route({ method: 'POST', path: '/echo' })
    .input(z.object({ message: z.string() }))
    .output(z.object({ echoed: z.string() })),
};

const tenantHeader = defineSdkClientContribution<{ tenantId: string }>()({
  protocol: { family: 'netscript.sdk-client', major: 1 },
  id: 'app:tenant-header',
  context: { tenantId: 'required' },
  headerKeys: ['x-tenant-id'],
  responseCache: {
    mode: 'partitioned',
    partition: ({ context }) => context.tenantId,
  },
  prepare: ({ context }) => ({
    headers: { 'x-tenant-id': context.tenantId },
  }),
});

const client = createServiceClient({
  contract,
  serviceName: 'tenant-service',
  contributions: [tenantHeader] as const,
});

await client.echo(
  { message: 'hello' },
  { context: { tenantId: 'tenant_123' } },
);

Authenticated generated service calls

defineService() refuses a missing auth policy. When auth is installed, netscript service add generates a browser-session authenticator and createContractAuthorizer(router). The contract marks protected procedures with access: { authentication: 'required', authorization: ... }; anonymous protected REST/RPC calls return 401, and authenticated authorization denials return 403. Procedures declaring authentication: 'none' stay public. The generated policy also leaves /health, /api/openapi.json, and /api/docs anonymous. Discovery is public; it does not bypass procedure authorization.

The generated app's server-only auth/bff.ts composes createBrowserSessionClient() with browserSessionContext(request). See the workspace tutorial for a request-handler call. To compose the same shipped seam directly, use createBearerSdkClientContribution from @netscript/plugin-auth-core/sdk:

// Authenticated workspace SDK client.
import { WorkspaceContractV1 } from '@my-workspace/contracts';
import { createBearerSdkClientContribution } from '@netscript/plugin-auth-core/sdk';
import { createServiceClient } from '@netscript/sdk/client';

const bearer = createBearerSdkClientContribution<{ accessToken?: string }>({
  context: { accessToken: 'optional' },
  resolveCredential: ({ context }) => context.accessToken,
  responseCache: { mode: 'direct-only' },
  unmarked: 'required',
});

const workspaceClient = createServiceClient({
  contract: WorkspaceContractV1,
  serviceName: 'workspace',
  routerName: 'workspace',
  contributions: [bearer] as const,
});

export async function listWorkspaceMembers(accessToken: string) {
  return await workspaceClient.members(
    { workspace: 'ws-1', limit: 20, offset: 0 },
    { context: { accessToken } },
  );
}

WorkspaceContractV1 is the shared contract from the tutorial; replace the workspace package name with your generated name. Pass the current verified session's opaque bearer to listWorkspaceMembers() on the server. Keep the literal contribution tuple and let both generic parameters infer: supplying only createServiceClient<typeof WorkspaceContractV1> selects the empty contribution default and loses the contributed context type.

The contribution owns authorization, emits Bearer, and resolves credentials only for protected procedures. Public (authentication: 'none') procedures receive no bearer; unmarked procedures in this example require one. A missing bearer for a required procedure rejects locally before any HTTP request, while service-side anonymous probes still return 401. direct-only keeps credentialed responses out of shared query caches. Credentials require HTTPS outside local development unless the caller explicitly permits insecure transport. Do not put tokens in cache keys, URLs, browser-visible data, or a shared client closure; supply them per call.

For a service whose entire surface is intentionally public, the exact policy opt-out is:

// Explicit public policy.
import type { ServiceAuthPolicy } from '@netscript/service/auth';

const auth = {
  public: true,
  reason: 'Public status service with no protected operations',
} satisfies ServiceAuthPolicy;

Pass auth in defineService(router, { name: 'status', auth }). This is an explicit, greppable migration from omitted auth, and disables service guards. It is separate from declaring one public procedure in a guarded contract. See explicit service posture. Background callers use the installation credential contribution below under their own service identity; they do not depend on a browser session.

Internal service credential contribution

createInternalCredentialSdkClientContribution({ service, secret?, allowInsecureTransport? }) sends the installation's internal credential for service as Authorization: Bearer …. Workers, sagas and triggers use it to call internal procedures, and session-guarded services that compose the internal-credential authenticator, under a service identity instead of an app or user session. Without secret, it loads NETSCRIPT_INSTALLATION_SECRET_FILE once. It derives the bearer once per contribution. Procedures declaring authentication: 'none' receive no credential. It is direct-only, so credentialed responses never enter a shared query cache. Non-loopback cleartext HTTP is refused unless allowInsecureTransport is set.

Server-side query factories (@netscript/sdk/query)

Cache engine (@netscript/sdk/cache)

Server-side only. Importing this subpath is inert. Custom server bootstraps must call setCacheProvider(cacheQuery) explicitly; defineFreshApp() does this for NetScript-managed Fresh apps.

Query client / TanStack integration (@netscript/sdk/query-client)

Browser- and island-facing TanStack Query integration.

Collections (@netscript/sdk/collections)

Service discovery (@netscript/sdk/discovery)

Resolves Aspire-managed service URLs and database/KV connections from environment variables. getServiceUrl reads the runtime globals; resolveServiceUrlFromSources is its pure counterpart over explicit sources, for runtimes without Vite or Deno.

Durable streams (@netscript/sdk/streams)

Server-side writers, schema helpers, and a DOM-independent streaming-fetch consumer for NetScript durable streams (State Protocol). createFetchStreamEventSourceV1 implements the existing StreamEventSourceV1 port and accepts a host streaming fetch, an optional per-connect auth provider, an abort signal, and finite heartbeat, reconnect, and buffer limits. It delivers plain event objects through bindStreamEventSourceV1. Data waits for a valid control before delivery and replay progress advances; reconnect uses the control's opaque offset plus SSE Last-Event-ID when available. See the SDK README for a complete transport example. The React Native collection binding, live-query hook, and Expo reference are described in the Expo streams how-to. Native Hermes runtime acceptance remains pending the device proof supplied with that reference.

Use @netscript/sdk/streams/consumer for the fetch source and binding in shared/browser/React Native code. Its import graph excludes telemetry, OTel, and modules using Deno.*. The wider ./streams facade retains server producer exports. Every non-2xx response (including 401/403/404) retries with fresh per-connect credentials. Server retry: is clamped to the configured initial back-off floor and cap. HTTP 204 and terminal control stop permanently.

The streams entry also exposes the SSE type closure from @netscript/plugin-streams-core/sse, including StreamEventSourceV1, BindStreamEventSourceOptionsV1, StreamEventSourceBindingV1, StreamSseConsumerEventV1, StreamSseReplayStateV1, and the versioned frame, payload, schema, and reduction types. Parsing and schema validation retain one authority in stream core.

Telemetry (@netscript/sdk/telemetry)

Ports (@netscript/sdk/ports)

Package-owned, upstream-type-free structural ports shared with other NetScript packages. The port surface re-exports the structural contracts documented in the sections above (QueryClientPort, CacheStore, ServiceMetadata, ServiceQueryUtils, HealthCheckResponse, PaginatedResponse, the service operation/key types, and the cache/contract structural aliases). Import from @netscript/sdk/ports when implementing or consuming these contracts without pulling in the concrete client, query, or cache engines.

OpenAPI helpers

Available from the root export.

Sub-path exports

The following entrypoints are published alongside the root export. Focused entries keep environment-specific adapters and dependencies out of consumers that do not need them.

Back to the reference overview.

React Native stream collections

createStreamCollectionV1 returns a stable collection, awaitable done, replay snapshot, and idempotent async dispose. StreamCollectionOptionsV1<T> extends the injected-source options with type, parse, and getKey. StreamCollectionV1<T> is the SDK's typed read/lifecycle port over a real TanStack collection. Narrow it with TanStack's isCollection guard and assign a typed Collection<T, string> local before passing it to q.from(...); filters, joins, and projections then preserve the entity types without assertions. StreamCollectionUtilsV1 exposes terminal-error inspection/subscription through the collection's utils, and StreamCollectionBindingV1<T> describes its connection lifecycle.

useStreamLiveQueryV1 from @netscript/sdk/streams/react wraps the upstream live-query hook with a StreamCollectionV1<TData> and returns StreamLiveQueryResultV1<TData> with data, status, and isLoading, and error. Fatal consumption failures reject pending preloads, clean up the collection, and leave the hook at status: 'error' with isLoading: false. A cleaned-up binding cannot restart; create a fresh binding before subscribing again. The focused entry imports React, without the Fresh runtime. This is a single-type State Protocol adapter, distinct from Fresh's multi-type schema-based StreamDB and its finite recovery policy. See the Expo how-to for lifecycle, fetch compatibility, and native proof requirements.