@namostack/plugin-sdk 0.0.1 → 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 namostack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1 +1,32 @@
-Not released yet. See https://docs.namostack.com
+# @namostack/plugin-sdk
+
+Build plugins for [namostack](https://app.namostack.com): talk to the app, store data for the current user, follow its theme.
+
+Start with the CLI, which sets this up for you: `npx @namostack/cli create`.
+
+```ts
+import { connect } from '@namostack/plugin-sdk';
+
+const namostack = await connect();
+namostack.onThemeChange((theme) => applyTheme(theme));
+
+await namostack.data.insert('plants', { name: 'Monstera', waterEveryDays: 7 });
+const { items } = await namostack.data.find('plants', {
+  sort: 'updatedAt',
+  order: 'desc',
+});
+```
+
+In `vite.config.ts`, add the Vite plugin every namostack plugin needs:
+
+```ts
+import { namostackPlugin } from '@namostack/plugin-sdk/vite';
+
+export default defineConfig({ plugins: [namostackPlugin()] });
+```
+
+The full guide: [docs.namostack.com](https://docs.namostack.com).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,145 @@
+import { z } from "zod";
+//#region ../../types/src/plugin-data.d.ts
+/** What `data.find` takes in the SDK, all optional. */
+declare const FindOptionsSchema: z.ZodObject<{
+  where: z.ZodOptional<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>, Record<string, string | number | boolean | null>, Record<string, string | number | boolean | null>>>;
+  sort: z.ZodDefault<z.ZodEnum<["createdAt", "updatedAt"]>>;
+  order: z.ZodDefault<z.ZodEnum<["asc", "desc"]>>;
+  limit: z.ZodDefault<z.ZodNumber>;
+  /** Opaque: the `cursor` of the previous page. */
+  cursor: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+  sort: "createdAt" | "updatedAt";
+  order: "asc" | "desc";
+  limit: number;
+  where?: Record<string, string | number | boolean | null> | undefined;
+  cursor?: string | undefined;
+}, {
+  sort?: "createdAt" | "updatedAt" | undefined;
+  where?: Record<string, string | number | boolean | null> | undefined;
+  order?: "asc" | "desc" | undefined;
+  limit?: number | undefined;
+  cursor?: string | undefined;
+}>;
+type FindOptions = z.input<typeof FindOptionsSchema>;
+//#endregion
+//#region ../../types/src/bridge.d.ts
+declare const BridgeErrorCodeSchema: z.ZodEnum<["permission_denied", "not_found", "validation_error", "quota_exceeded", "timeout", "upgrade_required", "internal"]>;
+type BridgeErrorCode = z.infer<typeof BridgeErrorCodeSchema>;
+/** Enough for a plugin using seedui: its `ThemeProvider` builds the rest from the mode. */
+declare const PluginThemeSchema: z.ZodObject<{
+  mode: z.ZodEnum<["light", "dark"]>;
+}, "strip", z.ZodTypeAny, {
+  mode: "light" | "dark";
+}, {
+  mode: "light" | "dark";
+}>;
+type PluginTheme = z.infer<typeof PluginThemeSchema>;
+/** What the plugin learns about itself and the app once connected. */
+declare const BridgeContextSchema: z.ZodObject<{
+  /** In live testing (`env: 'dev'`), the slug: the plugin may not be published yet. */
+  pluginId: z.ZodString;
+  slug: z.ZodString;
+  /** `dev` while live testing with `namostack dev`: its data is kept apart from real data. */
+  env: z.ZodEnum<["prod", "dev"]>;
+  name: z.ZodString;
+  version: z.ZodString;
+  theme: z.ZodObject<{
+    mode: z.ZodEnum<["light", "dark"]>;
+  }, "strip", z.ZodTypeAny, {
+    mode: "light" | "dark";
+  }, {
+    mode: "light" | "dark";
+  }>;
+  /** The browser's language, e.g. `en-US`. */
+  locale: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+  pluginId: string;
+  slug: string;
+  env: "prod" | "dev";
+  name: string;
+  version: string;
+  theme: {
+    mode: "light" | "dark";
+  };
+  locale: string;
+}, {
+  pluginId: string;
+  slug: string;
+  env: "prod" | "dev";
+  name: string;
+  version: string;
+  theme: {
+    mode: "light" | "dark";
+  };
+  locale: string;
+}>;
+type BridgeContext = z.infer<typeof BridgeContextSchema>;
+/** `user.getProfile()`: never the email. */
+declare const PluginUserProfileSchema: z.ZodObject<{
+  displayName: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+  displayName: string;
+}, {
+  displayName: string;
+}>;
+type PluginUserProfile = z.infer<typeof PluginUserProfileSchema>;
+declare const PluginNotificationSchema: z.ZodObject<{
+  message: z.ZodString;
+  tone: z.ZodDefault<z.ZodEnum<["info", "success", "warning", "error"]>>;
+}, "strip", z.ZodTypeAny, {
+  message: string;
+  tone: "error" | "info" | "success" | "warning";
+}, {
+  message: string;
+  tone?: "error" | "info" | "success" | "warning" | undefined;
+}>;
+type PluginNotification = z.input<typeof PluginNotificationSchema>;
+type NotificationTone = z.infer<typeof PluginNotificationSchema>['tone'];
+//#endregion
+//#region src/connect.d.ts
+/** A stored document: the plugin's fields next to the ones namostack sets. */
+type StoredDocument<TFields extends object = Record<string, unknown>> = TFields & {
+  id: string;
+  createdAt: string;
+  updatedAt: string;
+};
+interface FindResult<TFields extends object> {
+  items: StoredDocument<TFields>[];
+  /** Pass it back as `cursor` for the next page; absent once there's nothing more. */
+  cursor?: string;
+}
+/** What a plugin gets from `connect()`. Data is the current user's, for this plugin only. */
+interface Namostack {
+  /** As it was when connecting; follow theme changes with `onThemeChange`. */
+  context: BridgeContext;
+  data: {
+    find: <TFields extends object = Record<string, unknown>>(collection: string, options?: FindOptions) => Promise<FindResult<TFields>>;
+    get: <TFields extends object = Record<string, unknown>>(collection: string, id: string) => Promise<StoredDocument<TFields>>;
+    insert: <TFields extends object>(collection: string, fields: TFields) => Promise<StoredDocument<TFields>>;
+    /** Shallow merge: the patch's top-level fields replace the document's. */
+    update: <TFields extends object>(collection: string, id: string, patch: Partial<TFields>) => Promise<StoredDocument<TFields>>;
+    delete: (collection: string, id: string) => Promise<void>;
+  };
+  user: {
+    getProfile: () => Promise<PluginUserProfile>;
+  };
+  ui: {
+    notify: (notification: PluginNotification) => Promise<void>;
+    /** Sets the plugin frame's height, in CSS pixels. */
+    resize: (height: number) => Promise<void>;
+  };
+  /** Returns a function that stops listening. */
+  onThemeChange: (listener: (theme: PluginTheme) => void) => () => void;
+}
+/** Connects to the namostack app. Call it once, when the plugin starts. */
+export declare function connect(): Promise<Namostack>;
+//#endregion
+//#region src/errors.d.ts
+/** Every failed SDK call throws this; `message` is safe to show to the user. */
+export declare class BridgeError extends Error {
+  readonly code: BridgeErrorCode;
+  constructor(code: BridgeErrorCode, message: string);
+}
+//#endregion
+export type { BridgeContext, BridgeErrorCode, FindOptions, FindResult, Namostack, NotificationTone, PluginNotification, PluginTheme, PluginUserProfile, StoredDocument };

package/dist/index.js

@@ -0,0 +1,508 @@
+import { z } from "zod";
+import { CallOptions, ErrorCode, PenpalError, WindowMessenger, connect as connect$1 } from "penpal";
+//#region ../../types/src/auth.ts
+/** Trimmed and lowercased before every lookup, so `Ada@Example.com ` and `ada@example.com` are one account. */
+const EmailSchema = z.string().trim().toLowerCase().email().max(254);
+/** Rules for a new password (signup, password change). Login accepts any string, so old rules never lock anyone out. */
+const NewPasswordSchema = z.string().min(10, "Password must be at least 10 characters").max(256, "Password must be at most 256 characters").regex(/[a-z]/, "Password must contain a lowercase letter").regex(/[A-Z]/, "Password must contain an uppercase letter").regex(/[0-9]/, "Password must contain a digit").regex(/[^a-zA-Z0-9]/, "Password must contain a special character");
+const PasswordSchema = z.string().min(1).max(256);
+/** Always UTC (`…Z`): built with `Date#toISOString()`, never from a local-time string. */
+const TimestampSchema = z.string().datetime();
+z.object({
+	email: EmailSchema,
+	password: NewPasswordSchema,
+	displayName: z.string().trim().min(1).max(100)
+});
+z.object({
+	email: EmailSchema,
+	password: PasswordSchema
+});
+z.object({
+	current: PasswordSchema,
+	next: NewPasswordSchema
+});
+const UserSchema = z.object({
+	id: z.string(),
+	email: z.string(),
+	displayName: z.string()
+});
+z.object({ user: UserSchema });
+const SessionSummarySchema = z.object({
+	id: z.string(),
+	/** Raw `User-Agent` header, shown as the device. */
+	userAgent: z.string().optional(),
+	ip: z.string().optional(),
+	lastSeenAt: TimestampSchema,
+	/** The session making this request. */
+	current: z.boolean()
+});
+z.object({ sessions: z.array(SessionSummarySchema) });
+z.object({ token: z.string().min(1) });
+/** A request authenticated by the session cookie (the web app). */
+const SessionIdentitySchema = z.object({
+	kind: z.literal("session"),
+	userId: z.string(),
+	sessionId: z.string()
+});
+/** A request authenticated by a CLI access token (`Authorization: Bearer nst_pat_…`). */
+const CliTokenIdentitySchema = z.object({
+	kind: z.literal("cliToken"),
+	userId: z.string(),
+	tokenId: z.string()
+});
+z.discriminatedUnion("kind", [SessionIdentitySchema, CliTokenIdentitySchema]);
+const BridgeErrorCodeSchema = z.enum([
+	"permission_denied",
+	"not_found",
+	"validation_error",
+	"quota_exceeded",
+	"timeout",
+	"upgrade_required",
+	"internal"
+]);
+/** How a failed call crosses the bridge; `message` is safe to show. */
+const BridgeErrorBodySchema = z.object({
+	code: BridgeErrorCodeSchema.catch("internal"),
+	message: z.string()
+});
+z.object({ sdkVersion: z.string().min(1) });
+function bridgeResultSchema(value) {
+	return z.discriminatedUnion("ok", [z.object({
+		ok: z.literal(true),
+		value
+	}), z.object({
+		ok: z.literal(false),
+		error: BridgeErrorBodySchema
+	})]);
+}
+/** Enough for a plugin using seedui: its `ThemeProvider` builds the rest from the mode. */
+const PluginThemeSchema = z.object({ mode: z.enum(["light", "dark"]) });
+/** What the plugin learns about itself and the app once connected. */
+const BridgeContextSchema = z.object({
+	/** In live testing (`env: 'dev'`), the slug: the plugin may not be published yet. */
+	pluginId: z.string(),
+	slug: z.string(),
+	/** `dev` while live testing with `namostack dev`: its data is kept apart from real data. */
+	env: z.enum(["prod", "dev"]),
+	name: z.string(),
+	version: z.string(),
+	theme: PluginThemeSchema,
+	/** The browser's language, e.g. `en-US`. */
+	locale: z.string()
+});
+/** `user.getProfile()`: never the email. */
+const PluginUserProfileSchema = z.object({ displayName: z.string() });
+const PluginNotificationSchema = z.object({
+	message: z.string().trim().min(1).max(300),
+	tone: z.enum([
+		"info",
+		"success",
+		"warning",
+		"error"
+	]).default("info")
+});
+/** `ui.resize(height)`, in CSS pixels. */
+const FrameHeightSchema = z.number().int().min(0).max(1e5);
+const DocumentIdSchema = z.string().min(1);
+//#endregion
+//#region ../../types/src/cli.ts
+/** Shown in Settings → Developer; the CLI suggests its hostname, the user confirms it when approving. */
+const TokenNameSchema = z.string().trim().min(1).max(100);
+/** `WDJB-MJHT`: what the user checks in the browser against what the CLI printed. */
+const UserCodeSchema = z.string().trim().toUpperCase().regex(/^[A-Z]{4}-[A-Z]{4}$/, "Invalid code");
+z.object({ tokenName: TokenNameSchema });
+z.object({
+	/** Secret the CLI polls with; never shown to the user. */
+	deviceCode: z.string(),
+	userCode: z.string(),
+	/** The web app's approval page for this login. */
+	verifyUrl: z.string().url(),
+	/** Seconds to wait between polls. */
+	interval: z.number().int(),
+	/** Seconds before the login request expires. */
+	expiresIn: z.number().int()
+});
+z.object({ deviceCode: z.string().min(1) });
+z.discriminatedUnion("status", [
+	z.object({ status: z.literal("pending") }),
+	z.object({
+		status: z.literal("approved"),
+		/** `nst_pat_…`: the CLI stores it, the server only keeps its hash. */
+		token: z.string(),
+		expiresAt: TimestampSchema
+	}),
+	z.object({ status: z.literal("denied") }),
+	z.object({ status: z.literal("expired") })
+]);
+z.object({ userCode: UserCodeSchema });
+z.object({
+	userCode: z.string(),
+	tokenName: z.string()
+});
+z.object({
+	userCode: UserCodeSchema,
+	tokenName: TokenNameSchema
+});
+/** A CLI access token as Settings → Developer lists it; never the token itself. */
+const CliTokenSummarySchema = z.object({
+	id: z.string(),
+	name: z.string(),
+	/** Absent until the CLI first uses the token. */
+	lastUsedAt: TimestampSchema.optional(),
+	expiresAt: TimestampSchema
+});
+z.object({ tokens: z.array(CliTokenSummarySchema) });
+z.object({ tokenId: z.string().min(1) });
+z.object({ token: z.string().min(1) });
+//#endregion
+//#region ../../types/src/plugins.ts
+/** `public`: in the catalog. `unlisted`: installable by direct link. `private`: owner only. */
+const PluginVisibilitySchema = z.enum([
+	"public",
+	"unlisted",
+	"private"
+]);
+/** What a plugin can ask the host for; users see the list before installing. */
+const PluginPermissionSchema = z.enum([
+	"storage",
+	"user:profile:read",
+	"ui:notify"
+]);
+/** A plugin as the catalog lists it. */
+const CatalogPluginSchema = z.object({
+	id: z.string(),
+	slug: z.string(),
+	name: z.string(),
+	description: z.string(),
+	developerName: z.string(),
+	iconUrl: z.string().optional(),
+	isOfficial: z.boolean(),
+	installCount: z.number().int(),
+	/** The latest version's: what the user accepts when installing. */
+	permissions: z.array(PluginPermissionSchema)
+});
+z.object({ plugins: z.array(CatalogPluginSchema) });
+/** An installed plugin, with what the sidebar shows of it. */
+const InstalledPluginSchema = z.object({
+	pluginId: z.string(),
+	slug: z.string(),
+	/** `private` ones are the user's own (`/my-plugins/<slug>`). */
+	visibility: PluginVisibilitySchema,
+	name: z.string(),
+	iconUrl: z.string().optional(),
+	enabled: z.boolean(),
+	/** Order in the sidebar, ascending. */
+	position: z.number(),
+	installedAt: TimestampSchema,
+	/** The version the user installed or last updated to; newer ones wait for `update`. */
+	version: z.string(),
+	/** From that version's manifest: what the host's bridge lets it call. */
+	permissions: z.array(PluginPermissionSchema),
+	/** Present while a newer version is published. */
+	update: z.object({
+		version: z.string(),
+		/** Asked for by the new version only: the user must accept them, even with auto-update on. */
+		addedPermissions: z.array(PluginPermissionSchema)
+	}).optional()
+});
+z.object({
+	url: z.string().url(),
+	expiresAt: TimestampSchema
+});
+z.object({ installedPlugins: z.array(InstalledPluginSchema) });
+z.object({ pluginId: z.string().min(1) });
+z.object({ version: z.string().min(1) });
+z.object({ pluginId: z.string().min(1) });
+/** A plugin as its owner sees it in My plugins: its catalog card, plus what only the owner sees. */
+const MyPluginSchema = CatalogPluginSchema.extend({
+	visibility: PluginVisibilitySchema,
+	latestVersion: z.string()
+});
+z.object({ plugins: z.array(MyPluginSchema) });
+z.object({ visibility: PluginVisibilitySchema });
+//#endregion
+//#region ../../types/src/manifest.ts
+/** Globally unique, and the plugin's subdomain (`<slug>.namostack-plugins.com`). */
+const PluginSlugSchema = z.string().regex(/^[a-z][a-z0-9-]{2,39}$/, "Use 3–40 lowercase letters, digits or dashes, starting with a letter");
+/** Plain `MAJOR.MINOR.PATCH`: no pre-release tags, no leading zeros. */
+const PluginVersionSchema = z.string().regex(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/, "Use MAJOR.MINOR.PATCH, e.g. 1.2.0");
+const BundlePathSchema = z.string().min(1).refine((path) => !/^([/\\]|[a-zA-Z]:)/.test(path) && !/(^|[/\\])\.\.([/\\]|$)/.test(path), "Must be a relative path inside the bundle");
+/** `namostack.plugin.json`: checked by the CLI, and again by core-api on publish. */
+const PluginManifestSchema = z.object({
+	slug: PluginSlugSchema,
+	name: z.string().trim().min(1).max(50),
+	version: PluginVersionSchema,
+	description: z.string().trim().max(300),
+	/** HTML file the host frames. */
+	entry: BundlePathSchema.refine((path) => path.endsWith(".html"), "Must be an HTML file"),
+	icon: BundlePathSchema,
+	/** semver range of `@namostack/plugin-sdk` the plugin was built for. */
+	sdk: z.string().min(1),
+	permissions: z.array(PluginPermissionSchema).refine((permissions) => new Set(permissions).size === permissions.length, "Permissions must not repeat")
+});
+z.object({ slug: PluginSlugSchema });
+z.object({
+	slug: z.string(),
+	/** The caller has no plugin with this slug yet, so `namostack create` can use it. */
+	available: z.boolean(),
+	/** No public or unlisted plugin uses it: the new plugin could be published as one. */
+	publishable: z.boolean()
+});
+z.object({
+	slug: z.string(),
+	latestVersion: z.string(),
+	visibility: PluginVisibilitySchema
+});
+z.object({
+	manifest: PluginManifestSchema,
+	/** First publish only, as on `complete`: a public or unlisted one fails here if its slug is taken. */
+	visibility: PluginVisibilitySchema.optional()
+});
+z.object({
+	/** Pre-signed `PUT` for the gzipped tar of `dist/`. */
+	uploadUrl: z.string().url(),
+	/** Seconds the URL stays valid. */
+	expiresIn: z.number().int()
+});
+z.object({
+	slug: PluginSlugSchema,
+	version: PluginVersionSchema
+});
+z.object({
+	manifest: PluginManifestSchema,
+	/** First publish only; later publishes keep the plugin's visibility. Defaults to `private`. */
+	visibility: PluginVisibilitySchema.optional()
+});
+z.object({
+	slug: z.string(),
+	version: z.string(),
+	visibility: PluginVisibilitySchema,
+	/** Where the plugin can be found in the web app. */
+	url: z.string().url()
+});
+z.object({
+	/** The manifest on the author's disk: its permissions are the ones enforced. */
+	manifest: PluginManifestSchema,
+	/** `http://<slug>.dev.localhost:<port>/`, where `namostack dev` serves the plugin. */
+	devUrl: z.string().url()
+});
+z.object({
+	/** The plugin's live-testing page in the web app. */
+	url: z.string().url(),
+	/** Seconds before the session ends unless the CLI sends it again. */
+	expiresIn: z.number().int()
+});
+/** A plugin in live testing, as its author's web app shows it. */
+const DevSessionSchema = z.object({
+	slug: z.string(),
+	name: z.string(),
+	version: z.string(),
+	devUrl: z.string().url(),
+	/** From the local manifest; granted without consent, since the author tests their own plugin. */
+	permissions: z.array(PluginPermissionSchema),
+	iconUrl: z.string().optional(),
+	startedAt: TimestampSchema
+});
+z.object({ devSessions: z.array(DevSessionSchema) });
+const ErrorCodeSchema = z.enum([
+	"unauthenticated",
+	"invalid_credentials",
+	"permission_denied",
+	"not_found",
+	"email_unavailable",
+	"already_installed",
+	"slug_taken",
+	"rate_limited",
+	"quota_exceeded",
+	"validation_error",
+	"upgrade_required",
+	"internal"
+]);
+z.object({
+	code: ErrorCodeSchema.catch("internal"),
+	message: z.string()
+});
+//#endregion
+//#region ../../types/src/plugin-data.ts
+/** A plugin's collection, e.g. `tasks`: one per kind of document. */
+const CollectionNameSchema = z.string().regex(/^[a-z0-9_-]{1,64}$/, "Use 1–64 lowercase letters, digits, dashes or underscores");
+z.object({
+	pluginId: z.string().min(1),
+	collection: CollectionNameSchema
+}).extend({ id: z.string().min(1) });
+/** Set by plugin-api on every document, so a plugin can't write them. */
+const RESERVED_DOCUMENT_FIELDS = [
+	"id",
+	"createdAt",
+	"updatedAt"
+];
+/** What a plugin writes: insert takes the whole document, update the top-level fields it changes. */
+const DocumentFieldsSchema = z.record(z.unknown()).refine((fields) => RESERVED_DOCUMENT_FIELDS.every((field) => !Object.hasOwn(fields, field)), `${RESERVED_DOCUMENT_FIELDS.join(", ")} are set by namostack`);
+/** A stored document: the plugin's fields, flat, next to the ones plugin-api sets. */
+const PluginDocumentSchema = z.object({
+	id: z.string(),
+	createdAt: TimestampSchema,
+	updatedAt: TimestampSchema
+}).passthrough();
+const WhereValueSchema = z.union([
+	z.string(),
+	z.number(),
+	z.boolean(),
+	z.null()
+]);
+/** Top-level field → the value it must equal. */
+const DocumentWhereSchema = z.record(WhereValueSchema).refine((where) => RESERVED_DOCUMENT_FIELDS.every((field) => !Object.hasOwn(where, field)), `Can't filter on ${RESERVED_DOCUMENT_FIELDS.join(", ")}`);
+/** `?where=` is the same, as JSON. */
+const WhereQuerySchema = z.preprocess((value) => {
+	if (typeof value !== "string") return value;
+	try {
+		return JSON.parse(value);
+	} catch {
+		return value;
+	}
+}, DocumentWhereSchema);
+/** What `data.find` takes in the SDK, all optional. */
+const FindOptionsSchema = z.object({
+	where: DocumentWhereSchema.optional(),
+	sort: z.enum(["createdAt", "updatedAt"]).default("createdAt"),
+	order: z.enum(["asc", "desc"]).default("asc"),
+	limit: z.coerce.number().int().min(1).max(200).default(50),
+	/** Opaque: the `cursor` of the previous page. */
+	cursor: z.string().min(1).optional()
+});
+FindOptionsSchema.extend({ where: WhereQuerySchema.optional() });
+const FindResponseSchema = z.object({
+	items: z.array(PluginDocumentSchema),
+	/** Present while there may be more matching documents. */
+	cursor: z.string().optional()
+});
+//#endregion
+//#region ../../types/src/preferences.ts
+/** `system` follows the OS setting (`prefers-color-scheme`). */
+const ThemePreferenceSchema = z.enum([
+	"light",
+	"dark",
+	"system"
+]);
+z.object({
+	theme: ThemePreferenceSchema,
+	sidebarCollapsed: z.boolean(),
+	/** Applies plugin updates on its own, except those adding permissions. */
+	autoUpdatePlugins: z.boolean()
+});
+//#endregion
+//#region src/config.ts
+const SECOND_MS = 1e3;
+/** Every rule the SDK runs on. Durations are in milliseconds. */
+const SDK_CONFIG = {
+	/** The only hosts a plugin talks to: the namostack app, per environment. */
+	appOrigins: [
+		"https://app.namostack.com",
+		"https://app.staging.namostack.com",
+		"https://app.namostack.localhost:5173"
+	],
+	/** Opened anywhere but inside the app, `connect()` gives up after this. */
+	connectTimeoutMs: 10 * SECOND_MS,
+	/** Per bridge call. */
+	callTimeoutMs: 10 * SECOND_MS
+};
+//#endregion
+//#region src/errors.ts
+/** Every failed SDK call throws this; `message` is safe to show to the user. */
+var BridgeError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "BridgeError";
+		this.code = code;
+	}
+};
+//#endregion
+//#region src/version.ts
+/** Sent to the app when connecting, so it can turn away SDKs too old to work with it. */
+const SDK_VERSION = "0.1.0-rc.1";
+//#endregion
+//#region src/connect.ts
+const NullSchema = z.null();
+/** Arguments are checked here too, so a mistake fails before crossing the bridge. */
+function parseArgument(schema, value) {
+	const parsed = schema.safeParse(value);
+	if (!parsed.success) throw new BridgeError("validation_error", parsed.error.issues[0]?.message ?? "Invalid argument");
+	return parsed.data;
+}
+/** Runs one host method and unwraps its result, which is never trusted as is. */
+async function call(schema, invoke) {
+	let answer;
+	try {
+		answer = await invoke(new CallOptions({ timeout: SDK_CONFIG.callTimeoutMs }));
+	} catch (error) {
+		if (error instanceof PenpalError && error.code === ErrorCode.MethodCallTimeout) throw new BridgeError("timeout", "namostack took too long to answer.");
+		throw new BridgeError("internal", "The call to namostack failed.");
+	}
+	const result = bridgeResultSchema(schema).safeParse(answer);
+	if (!result.success) throw new BridgeError("internal", "namostack sent an unexpected answer.");
+	const outcome = result.data;
+	if (!outcome.ok) throw new BridgeError(outcome.error.code, outcome.error.message);
+	return outcome.value;
+}
+/** Waits for the namostack app framing this plugin; only the app's own origins are accepted. */
+async function connectToHost(methods) {
+	const notInApp = new BridgeError("internal", "Plugins only run inside the namostack app.");
+	if (window.parent === window) throw notInApp;
+	const connection = connect$1({
+		messenger: new WindowMessenger({
+			remoteWindow: window.parent,
+			allowedOrigins: [...SDK_CONFIG.appOrigins]
+		}),
+		methods,
+		timeout: SDK_CONFIG.connectTimeoutMs
+	});
+	try {
+		return await connection.promise;
+	} catch {
+		throw notInApp;
+	}
+}
+/** Connects to the namostack app. Call it once, when the plugin starts. */
+async function connect() {
+	const themeListeners = /* @__PURE__ */ new Set();
+	const host = await connectToHost({ onThemeChange: (theme) => {
+		const parsed = PluginThemeSchema.safeParse(theme);
+		if (parsed.success) themeListeners.forEach((listener) => listener(parsed.data));
+	} });
+	return {
+		context: await call(BridgeContextSchema, (options) => host.getContext({ sdkVersion: SDK_VERSION }, options)),
+		data: {
+			find: async (collection, options = {}) => {
+				return await call(FindResponseSchema, (callOptions) => host.data.find(parseArgument(CollectionNameSchema, collection), parseArgument(FindOptionsSchema, options), callOptions));
+			},
+			get: async (collection, id) => {
+				return await call(PluginDocumentSchema, (options) => host.data.get(parseArgument(CollectionNameSchema, collection), parseArgument(DocumentIdSchema, id), options));
+			},
+			insert: async (collection, fields) => {
+				return await call(PluginDocumentSchema, (options) => host.data.insert(parseArgument(CollectionNameSchema, collection), parseArgument(DocumentFieldsSchema, fields), options));
+			},
+			update: async (collection, id, patch) => {
+				return await call(PluginDocumentSchema, (options) => host.data.update(parseArgument(CollectionNameSchema, collection), parseArgument(DocumentIdSchema, id), parseArgument(DocumentFieldsSchema, patch), options));
+			},
+			delete: async (collection, id) => {
+				await call(NullSchema, (options) => host.data.delete(parseArgument(CollectionNameSchema, collection), parseArgument(DocumentIdSchema, id), options));
+			}
+		},
+		user: { getProfile: () => call(PluginUserProfileSchema, (options) => host.user.getProfile(options)) },
+		ui: {
+			notify: async (notification) => {
+				await call(NullSchema, (options) => host.ui.notify(parseArgument(PluginNotificationSchema, notification), options));
+			},
+			resize: async (height) => {
+				await call(NullSchema, (options) => host.ui.resize(parseArgument(FrameHeightSchema, height), options));
+			}
+		},
+		onThemeChange: (listener) => {
+			themeListeners.add(listener);
+			return () => themeListeners.delete(listener);
+		}
+	};
+}
+//#endregion
+export { BridgeError, connect };

package/dist/vite.d.ts

@@ -0,0 +1,8 @@
+import { Plugin } from "vite";
+//#region src/vite.d.ts
+/**
+ * Vite settings every namostack plugin needs. Bundles are served under `/<version>/`,
+ * so asset URLs must be relative.
+ */
+export declare function namostackPlugin(): Plugin;
+//#endregion

package/dist/vite.js

@@ -0,0 +1,13 @@
+//#region src/vite.ts
+/**
+* Vite settings every namostack plugin needs. Bundles are served under `/<version>/`,
+* so asset URLs must be relative.
+*/
+function namostackPlugin() {
+	return {
+		name: "namostack",
+		config: () => ({ base: "./" })
+	};
+}
+//#endregion
+export { namostackPlugin };

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@namostack/plugin-sdk",
-  "version": "0.0.1",
-  "description": "Not released yet: see https://docs.namostack.com",
-  "license": "MIT"
-}
+  "version": "0.1.0-rc.1",
+  "description": "Build plugins for namostack: talk to the app, store data, follow its theme.",
+  "license": "MIT",
+  "homepage": "https://docs.namostack.com",
+  "keywords": [
+    "namostack",
+    "plugin",
+    "sdk"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "default": "./dist/vite.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "penpal": "^8.0.1",
+    "zod": "^3.23.0"
+  },
+  "peerDependencies": {
+    "vite": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "tsdown": "^0.23.1",
+    "typescript": "~6.0.2",
+    "vite": "^8.3.0",
+    "@namostack/tsconfig": "0.0.0",
+    "@namostack/types": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint": "oxlint",
+    "typecheck": "tsc -b"
+  }
+}