@checkstack/tips-common 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,46 @@
+# @checkstack/tips-common
+
+## 0.2.0
+
+### Minor Changes
+
+- 3547670: Add `@checkstack/tips-*` — first-run tip and onboarding infrastructure for
+  the frontends.
+
+  Three new packages:
+
+  - `@checkstack/tips-common` — RPC contract (`tipsContract`), `TipsApi`
+    client definition, and zod schemas. Fully-qualified tip IDs have shape
+    `<pluginId>.<localTipId>` and are produced exclusively by
+    `qualifyTipId(plugin, localId)` — plugins never write the namespace
+    themselves, and a local id with a leading or trailing `.` is rejected,
+    so one plugin cannot forge or dismiss a tip in another plugin's
+    namespace.
+  - `@checkstack/tips-backend` — Postgres-backed dismissal store
+    (`user_tip_dismissal` with composite PK on `(user_id, tip_id)`),
+    `listDismissed` / `dismiss` / `reset` endpoints scoped to the
+    requesting user via the auto-auth middleware, and a
+    `auth.userDeleted` hook that cleans up dismissals when a user is
+    deleted.
+  - `@checkstack/tips-frontend` — `<Tip>` (anchored popover) and
+    `<TipBanner>` (inline callout) components plus the `useTipState`
+    hook. All three accept `{ plugin, id }` (where `plugin` is the
+    caller's `pluginMetadata`) and route through `qualifyTipId` so the
+    namespace prefix is enforced at the boundary. Persists per-user on
+    the server when logged in, and per-browser in `localStorage`
+    (`checkstack.tips.dismissed`) when anonymous, with cross-tab sync via
+    the `storage` event.
+
+  `@checkstack/ui`'s `<EmptyState>` gains optional `steps` and `actions`
+  props for richer empty-state coaching (numbered onboarding lists +
+  primary CTA), and accepts `ReactNode` for `description`. Existing
+  callers continue to work unchanged.
+
+  `@checkstack/test-utils-backend`'s `createMockDb` now also mocks
+  `insert().values().onConflictDoNothing()` so routers using upsert-or-skip
+  semantics can be unit-tested.
+
+### Patch Changes
+
+- Updated dependencies [42abfff]
+  - @checkstack/common@0.9.0

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@checkstack/tips-common",
+  "version": "0.2.0",
+  "license": "Elastic-2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@checkstack/common": "0.8.0",
+    "@orpc/contract": "^1.13.14",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@checkstack/tsconfig": "0.0.7",
+    "@checkstack/scripts": "0.3.0",
+    "typescript": "^5.7.2"
+  },
+  "scripts": {
+    "typecheck": "tsgo -b",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0",
+    "test": "bun test"
+  },
+  "checkstack": {
+    "type": "common"
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./rpc-contract";
+export * from "./plugin-metadata";

package/src/plugin-metadata.ts

@@ -0,0 +1,9 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+/**
+ * Plugin metadata for the tips plugin.
+ * Powers the per-user dismissable tip infrastructure used by all frontends.
+ */
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "tips",
+});

package/src/rpc-contract.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect } from "bun:test";
+import {
+  LocalTipIdSchema,
+  TipIdSchema,
+  qualifyTipId,
+} from "./rpc-contract";
+
+describe("LocalTipIdSchema", () => {
+  it("accepts simple identifiers", () => {
+    expect(LocalTipIdSchema.parse("first-run")).toBe("first-run");
+    expect(LocalTipIdSchema.parse("systems_create")).toBe("systems_create");
+  });
+
+  it("accepts dotted sub-grouping inside the local part", () => {
+    expect(LocalTipIdSchema.parse("systems.create.first-time")).toBe(
+      "systems.create.first-time",
+    );
+  });
+
+  it("rejects a leading dot — would let a plugin escape its namespace", () => {
+    expect(() => LocalTipIdSchema.parse(".other-plugin.tip")).toThrow();
+  });
+
+  it("rejects a trailing dot", () => {
+    expect(() => LocalTipIdSchema.parse("systems.")).toThrow();
+  });
+
+  it("rejects whitespace and special characters", () => {
+    expect(() => LocalTipIdSchema.parse("systems create")).toThrow();
+    expect(() => LocalTipIdSchema.parse("systems!create")).toThrow();
+    expect(() => LocalTipIdSchema.parse("systems/create")).toThrow();
+  });
+
+  it("rejects empty strings", () => {
+    expect(() => LocalTipIdSchema.parse("")).toThrow();
+  });
+});
+
+describe("TipIdSchema (fully qualified)", () => {
+  it("requires a namespace separator", () => {
+    expect(() => TipIdSchema.parse("no-separator")).toThrow();
+  });
+
+  it("accepts well-formed `<plugin>.<local>` IDs", () => {
+    expect(TipIdSchema.parse("catalog.systems.create")).toBe(
+      "catalog.systems.create",
+    );
+  });
+});
+
+describe("qualifyTipId", () => {
+  const catalog = { pluginId: "catalog" };
+
+  it("prefixes the calling plugin's id", () => {
+    expect(qualifyTipId(catalog, "systems.create")).toBe(
+      "catalog.systems.create",
+    );
+  });
+
+  it("rejects a local id that tries to escape into another namespace", () => {
+    // A malicious plugin trying to silently dismiss someone else's tip:
+    // `qualifyTipId({ pluginId: "evil" }, ".healthcheck.first-run")` would,
+    // without validation, produce `"evil..healthcheck.first-run"` (still
+    // distinct, harmless) — but a leading dot is still rejected so the
+    // construction is impossible regardless of intent.
+    expect(() => qualifyTipId(catalog, ".healthcheck.first-run")).toThrow();
+  });
+
+  it("rejects dangerous separators that could spoof structure", () => {
+    expect(() => qualifyTipId(catalog, "../healthcheck/first-run")).toThrow();
+  });
+
+  it("returns a value that itself parses as a fully-qualified TipId", () => {
+    const id = qualifyTipId(catalog, "systems.create");
+    expect(() => TipIdSchema.parse(id)).not.toThrow();
+  });
+});

package/src/rpc-contract.ts

@@ -0,0 +1,140 @@
+import {
+  createClientDefinition,
+  proc,
+  type PluginMetadata,
+} from "@checkstack/common";
+import { pluginMetadata } from "./plugin-metadata";
+import { z } from "zod";
+
+/**
+ * Fully-qualified tip identifier — the wire format used in RPC payloads and
+ * stored in the database.
+ *
+ * Shape: `<pluginId>.<localTipId>`. The `.` is the namespace separator and
+ * MUST appear at least once. Plugins cannot construct a fully-qualified ID
+ * directly — they must go through `qualifyTipId` (or the frontend hooks /
+ * components, which call it for them) which prefixes the caller's own
+ * `pluginId` and rejects local IDs that contain a `.` themselves. This is
+ * what prevents one plugin from forging a tip in another plugin's
+ * namespace.
+ */
+export const TipIdSchema = z
+  .string()
+  .min(3)
+  .max(200)
+  .regex(/^[a-zA-Z0-9_-]+\.[a-zA-Z0-9._-]+$/, {
+    message:
+      "Tip IDs must be `<pluginId>.<localTipId>` and contain only letters, numbers, dots, dashes and underscores",
+  });
+
+export type TipId = z.infer<typeof TipIdSchema>;
+
+/**
+ * Local (post-namespace) tip identifier.
+ *
+ * This is what a plugin author writes in their code — e.g. `"systems.create"`
+ * — and explicitly forbids the namespace separator at the start so a plugin
+ * cannot author a tip that masquerades as belonging to another plugin.
+ *
+ * Allowed characters: letters, numbers, dots, dashes, underscores. The dot
+ * is allowed *inside* the local part for further sub-grouping (e.g.
+ * `"systems.create.first-time"`), but a leading or trailing dot is rejected
+ * so the concatenation with `<pluginId>.` always produces a well-formed
+ * fully-qualified ID with exactly one separator at the boundary.
+ */
+export const LocalTipIdSchema = z
+  .string()
+  .min(1)
+  .max(150)
+  .regex(/^[a-zA-Z0-9_-](?:[a-zA-Z0-9._-]*[a-zA-Z0-9_-])?$/, {
+    message:
+      "Local tip IDs may contain letters, numbers, dots, dashes and underscores, and must not start or end with a dot",
+  });
+
+export type LocalTipId = z.infer<typeof LocalTipIdSchema>;
+
+/**
+ * Qualify a local tip ID with the calling plugin's namespace.
+ *
+ * This is the ONLY supported way to produce a fully-qualified tip ID from
+ * plugin code. Both the local ID and the resulting fully-qualified ID are
+ * validated at runtime, so:
+ *
+ * - A plugin cannot pass a local ID containing a leading dot (e.g.
+ *   `".other-plugin.tip"`) to escape into another namespace.
+ * - The frontend hooks and components (`useTipState`, `<Tip>`,
+ *   `<TipBanner>`) accept only `(plugin, localId)` pairs and route through
+ *   this helper, so they cannot bypass namespacing either.
+ */
+export const qualifyTipId = (
+  plugin: Pick<PluginMetadata, "pluginId">,
+  localId: string,
+): TipId => {
+  const parsedLocal = LocalTipIdSchema.parse(localId);
+  const fullyQualified = `${plugin.pluginId}.${parsedLocal}`;
+  return TipIdSchema.parse(fullyQualified);
+};
+
+/** Server-returned dismissed tip record. */
+export const DismissedTipSchema = z.object({
+  tipId: TipIdSchema,
+  dismissedAt: z.date(),
+});
+export type DismissedTip = z.infer<typeof DismissedTipSchema>;
+
+/**
+ * Tips RPC Contract.
+ *
+ * All endpoints are scoped to the requesting user — there is no cross-user
+ * read or admin surface.
+ */
+export const tipsContract = {
+  /** List tip IDs the current user has dismissed. */
+  listDismissed: proc({
+    operationType: "query",
+    userType: "user",
+    access: [],
+  }).output(
+    z.object({
+      dismissed: z.array(DismissedTipSchema),
+    }),
+  ),
+
+  /** Mark a tip as dismissed for the current user. Idempotent. */
+  dismiss: proc({
+    operationType: "mutation",
+    userType: "user",
+    access: [],
+  })
+    .input(
+      z.object({
+        tipId: TipIdSchema,
+      }),
+    )
+    .output(z.void()),
+
+  /**
+   * Reset (un-dismiss) tips for the current user.
+   *
+   * If `tipIds` is omitted, ALL of the user's dismissed tips are cleared
+   * (used by the "replay onboarding" affordance).
+   */
+  reset: proc({
+    operationType: "mutation",
+    userType: "user",
+    access: [],
+  })
+    .input(
+      z.object({
+        tipIds: z.array(TipIdSchema).optional(),
+      }),
+    )
+    .output(z.void()),
+};
+
+export type TipsContract = typeof tipsContract;
+
+/**
+ * Client definition for type-safe `rpcApi.forPlugin(TipsApi)` usage.
+ */
+export const TipsApi = createClientDefinition(tipsContract, pluginMetadata);

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "@checkstack/tsconfig/common.json",
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../common"
+    }
+  ]
+}