@spacefast/common 0.0.3 → 0.0.6

package/dist/contracts/docs.d.ts

@@ -0,0 +1,119 @@
+import { z } from "zod";
+/** Disclosure tiers an entry can carry, default `essential` for listings. */
+export declare const DOC_TIERS: readonly ["essential", "full", "reference"];
+export declare const docsIndexQuerySchema: z.ZodObject<{
+    q: z.ZodOptional<z.ZodString>;
+    tier: z.ZodDefault<z.ZodEnum<{
+        essential: "essential";
+        full: "full";
+        reference: "reference";
+    }>>;
+    category: z.ZodOptional<z.ZodEnum<{
+        api: "api";
+        guide: "guide";
+        cli: "cli";
+        error: "error";
+        recipe: "recipe";
+        workflow: "workflow";
+    }>>;
+}, z.core.$strip>;
+/** Links carried by every docs entry. */
+export declare const DocsLinksSchema: z.ZodObject<{
+    doc: z.ZodString;
+    self: z.ZodString;
+}, z.core.$strip>;
+/** One entry in the docs index. */
+export declare const DocsEntrySchema: z.ZodObject<{
+    slug: z.ZodString;
+    title: z.ZodString;
+    summary: z.ZodString;
+    category: z.ZodEnum<{
+        api: "api";
+        guide: "guide";
+        cli: "cli";
+        error: "error";
+        recipe: "recipe";
+        workflow: "workflow";
+    }>;
+    tier: z.ZodEnum<{
+        essential: "essential";
+        full: "full";
+        reference: "reference";
+    }>;
+    keywords: z.ZodArray<z.ZodString>;
+    url: z.ZodString;
+    links: z.ZodObject<{
+        doc: z.ZodString;
+        self: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type DocsEntry = z.infer<typeof DocsEntrySchema>;
+/** A single doc, which additionally carries its printable body. */
+export declare const DocsDocSchema: z.ZodObject<{
+    slug: z.ZodString;
+    title: z.ZodString;
+    summary: z.ZodString;
+    category: z.ZodEnum<{
+        api: "api";
+        guide: "guide";
+        cli: "cli";
+        error: "error";
+        recipe: "recipe";
+        workflow: "workflow";
+    }>;
+    tier: z.ZodEnum<{
+        essential: "essential";
+        full: "full";
+        reference: "reference";
+    }>;
+    keywords: z.ZodArray<z.ZodString>;
+    url: z.ZodString;
+    links: z.ZodObject<{
+        doc: z.ZodString;
+        self: z.ZodString;
+    }, z.core.$strip>;
+    body: z.ZodString;
+}, z.core.$strip>;
+export type DocsDoc = z.infer<typeof DocsDocSchema>;
+/** The GET /v1/docs index payload (inside the `{ data }` envelope). */
+export declare const DocsIndexResponseSchema: z.ZodObject<{
+    tier: z.ZodEnum<{
+        essential: "essential";
+        full: "full";
+        reference: "reference";
+    }>;
+    query: z.ZodNullable<z.ZodString>;
+    category: z.ZodNullable<z.ZodEnum<{
+        api: "api";
+        guide: "guide";
+        cli: "cli";
+        error: "error";
+        recipe: "recipe";
+        workflow: "workflow";
+    }>>;
+    count: z.ZodNumber;
+    entries: z.ZodArray<z.ZodObject<{
+        slug: z.ZodString;
+        title: z.ZodString;
+        summary: z.ZodString;
+        category: z.ZodEnum<{
+            api: "api";
+            guide: "guide";
+            cli: "cli";
+            error: "error";
+            recipe: "recipe";
+            workflow: "workflow";
+        }>;
+        tier: z.ZodEnum<{
+            essential: "essential";
+            full: "full";
+            reference: "reference";
+        }>;
+        keywords: z.ZodArray<z.ZodString>;
+        url: z.ZodString;
+        links: z.ZodObject<{
+            doc: z.ZodString;
+            self: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;

package/dist/contracts/docs.js

@@ -0,0 +1,51 @@
+// Public contract for the machine-readable docs index API (GET /v1/docs and
+// GET /v1/docs/:slug). Tier values come from the shared CLI disclosure tiers and
+// categories from the shared docs catalog, so the API can never describe a tier
+// or category the catalog does not produce.
+import { z } from "zod";
+import { DOC_KINDS } from "../docs/catalog.js";
+import { CLI_DISCLOSURE_TIER_ORDER } from "../vocabulary.js";
+/** Disclosure tiers an entry can carry, default `essential` for listings. */
+export const DOC_TIERS = CLI_DISCLOSURE_TIER_ORDER;
+const docTierEnum = z.enum([...DOC_TIERS]);
+const docCategoryEnum = z.enum([...DOC_KINDS]);
+// Query for GET /v1/docs. Tier-aware: defaults to `essential`; pass
+// `tier=reference` to get EVERYTHING (tiers are cumulative). Optional `q`
+// free-text search and `category` filter compose with the tier.
+export const docsIndexQuerySchema = z.object({
+    q: z.string().optional().describe("Free-text search across slug, title, summary, and keywords."),
+    tier: docTierEnum
+        .default("essential")
+        .describe("Disclosure tier to list. `essential` (default) shows the core pages; `full` adds advanced pages; `reference` returns everything."),
+    category: docCategoryEnum
+        .optional()
+        .describe("Restrict to one docs area: guide, cli, api, recipe, workflow, or error."),
+});
+/** Links carried by every docs entry. */
+export const DocsLinksSchema = z.object({
+    doc: z.string().url().describe("Canonical human-readable docs URL."),
+    self: z.string().describe("API-relative link to this entry's JSON (`/v1/docs/{slug}`)."),
+});
+/** One entry in the docs index. */
+export const DocsEntrySchema = z.object({
+    slug: z.string().describe("Stable topic id, e.g. `publishing` or `api/spaces`."),
+    title: z.string(),
+    summary: z.string(),
+    category: docCategoryEnum,
+    tier: docTierEnum,
+    keywords: z.array(z.string()).describe("Extra search terms that match this page."),
+    url: z.string().url().describe("Canonical human-readable docs URL."),
+    links: DocsLinksSchema,
+});
+/** A single doc, which additionally carries its printable body. */
+export const DocsDocSchema = DocsEntrySchema.extend({
+    body: z.string().describe("Short printable explanation of the topic."),
+});
+/** The GET /v1/docs index payload (inside the `{ data }` envelope). */
+export const DocsIndexResponseSchema = z.object({
+    tier: docTierEnum.describe("The tier the listing ran at."),
+    query: z.string().nullable().describe("The trimmed `q` query, or null when listing."),
+    category: docCategoryEnum.nullable().describe("The applied category filter, or null."),
+    count: z.number().int().describe("Number of entries returned."),
+    entries: z.array(DocsEntrySchema),
+});