@tuwaio/docs-ui 0.2.0 → 0.3.0

package/dist/policies.d.ts

@@ -0,0 +1,88 @@
+/** Slug of a TUWA policy: the path of its page on the TUWA sites and the name of its files in `TuwaIO/workflows/docs`. */
+type PolicySlug = 'terms' | 'privacy' | 'cookie' | 'refund' | 'security' | 'dpa';
+/** A TUWA policy, as listed in {@link policies}. */
+interface Policy {
+    /** Slug of the policy. */
+    slug: PolicySlug;
+    /** Title shown in footers and on the page. */
+    title: string;
+    /** One sentence on what the policy covers, for policy lists. */
+    description: string;
+    /** Path of the policy page on the website and the Quasar dashboard. */
+    href: `/${PolicySlug}`;
+    /** Whether the policy is in force. Drafts stay `false` until they are approved. */
+    published: boolean;
+    /** Whether footers link the policy (default: `true`); documents linked from other policies set `false`. */
+    footer?: boolean;
+}
+/** A section of a policy: a level-2 heading with its anchor. */
+interface PolicySection {
+    /** Anchor of the heading, without `#` (stable when sections are renumbered). */
+    id: string;
+    /** Text of the heading without its number. */
+    title: string;
+}
+/** Content of a policy page, generated next to its PDF by `generate_pdf.js` in `TuwaIO/workflows/docs`. */
+interface PolicyContent {
+    /** Title of the document. */
+    title: string;
+    /** Date of the current version as written in the document (`October 8, 2026`). */
+    updated: string;
+    /** Level-2 sections in document order. */
+    sections: PolicySection[];
+    /** Body of the document as HTML, without the title and the date line; headings carry their anchors as `id`. */
+    html: string;
+}
+/** Where the policy files live: the `docs` folder of `TuwaIO/workflows` on GitHub, branch `main`. */
+declare const POLICY_SOURCE = "https://raw.githubusercontent.com/TuwaIO/workflows/main/docs";
+/** The site that hosts the policy pages; sites without their own policy pages (documentation sites) link there. */
+declare const POLICY_SITE_URL = "https://tuwa.io";
+/** The page that lists every TUWA policy in force: `/policies` of the docs hub. */
+declare const POLICIES_INDEX_URL = "https://docs.tuwa.io/policies";
+/**
+ * Every TUWA policy in the order footers list them. Footers of the website and the Quasar dashboard read
+ * {@link publishedPolicies}, so a policy appears everywhere once it is published.
+ */
+declare const policies: readonly Policy[];
+/** The policies in force, for policy lists: {@link policies} with `published: true`. */
+declare const publishedPolicies: readonly Policy[];
+/** The policies that footers link: {@link publishedPolicies} without those marked `footer: false`. */
+declare const footerPolicies: readonly Policy[];
+/**
+ * Returns the absolute URL of a policy page, for sites that do not host the policies themselves.
+ *
+ * @param slug - Slug of the policy.
+ * @param site - Origin of the site with the policy pages (default: {@link POLICY_SITE_URL}).
+ * @returns The URL of the page, for example `https://tuwa.io/terms`.
+ */
+declare function getPolicyPageUrl(slug: PolicySlug, site?: string): string;
+/**
+ * Returns the URL of a policy file.
+ *
+ * @param slug - Slug of the policy.
+ * @param format - `json` for the page content, `pdf` for the official document, `md` for the source text.
+ * @param source - Base URL of the policy files (default: {@link POLICY_SOURCE}).
+ * @returns The URL of the file.
+ */
+declare function getPolicyFileUrl(slug: PolicySlug, format: 'json' | 'pdf' | 'md', source?: string): string;
+/**
+ * Loads the content of a policy page (its `json` file). Call it on the server, for example in a Server Component of
+ * the Next.js App Router, and pass the result to `PolicyDocument`.
+ *
+ * Network: one request to `getPolicyFileUrl(slug, 'json', source)` per revalidation, cached by the Next.js `fetch`
+ * cache for `revalidate` seconds (outside Next.js, a plain request).
+ *
+ * @param slug - Slug of the policy.
+ * @param options - Optional settings.
+ * @param options.source - Base URL of the policy files (default: {@link POLICY_SOURCE}).
+ * @param options.revalidate - Seconds the Next.js `fetch` cache keeps the content, or `false` to cache it until the
+ *   next deployment (default: 3600).
+ * @returns The content of the policy.
+ * @throws Error when the request fails, the response is not `2xx`, or the file is not a policy page.
+ */
+declare function loadPolicy(slug: PolicySlug, options?: {
+    source?: string;
+    revalidate?: number | false;
+}): Promise<PolicyContent>;
+
+export { POLICIES_INDEX_URL, POLICY_SITE_URL, POLICY_SOURCE, type Policy, type PolicyContent, type PolicySection, type PolicySlug, footerPolicies, getPolicyFileUrl, getPolicyPageUrl, loadPolicy, policies, publishedPolicies };

package/dist/policies.js

@@ -0,0 +1,92 @@
+const POLICY_SOURCE = "https://raw.githubusercontent.com/TuwaIO/workflows/main/docs";
+const POLICY_SITE_URL = "https://tuwa.io";
+const POLICIES_INDEX_URL = "https://docs.tuwa.io/policies";
+const policies = [
+  {
+    slug: "terms",
+    title: "Terms of Service",
+    description: "The rules for using the TUWA websites and documentation, Quasar Cloud, Quasar Community Edition and the open-source packages.",
+    href: "/terms",
+    published: true
+  },
+  {
+    slug: "privacy",
+    title: "Privacy Policy",
+    description: "What data TUWA collects and why, how it is protected, and how to access or delete it.",
+    href: "/privacy",
+    published: true
+  },
+  {
+    slug: "cookie",
+    title: "Cookie Policy",
+    description: "The cookies and Local Storage that the TUWA sites and the Quasar dashboard use.",
+    href: "/cookie",
+    published: true
+  },
+  {
+    slug: "refund",
+    title: "Refund Policy",
+    description: "When and how payments for Quasar Cloud quota are refunded.",
+    href: "/refund",
+    // Quota purchases are paused; the policy is published again when they reopen
+    published: false
+  },
+  {
+    slug: "security",
+    title: "Security Policy",
+    description: "How to report a vulnerability, what TUWA promises in return, and who is responsible for what.",
+    href: "/security",
+    published: true
+  },
+  {
+    slug: "dpa",
+    title: "Data Processing Addendum",
+    description: "How we process the personal data of your app users on your behalf when you use Quasar Cloud.",
+    href: "/dpa",
+    published: true,
+    footer: false
+  }
+];
+const publishedPolicies = policies.filter((policy) => policy.published);
+const footerPolicies = publishedPolicies.filter((policy) => policy.footer !== false);
+function getPolicyPageUrl(slug, site = POLICY_SITE_URL) {
+  return `${site.replace(/\/+$/, "")}/${slug}`;
+}
+function getPolicyFileUrl(slug, format, source = POLICY_SOURCE) {
+  return `${source.replace(/\/+$/, "")}/${slug}.${format}`;
+}
+function isPolicyContent(value) {
+  if (!value || typeof value !== "object") return false;
+  const content = value;
+  return typeof content.title === "string" && typeof content.updated === "string" && typeof content.html === "string" && Array.isArray(content.sections) && content.sections.every(
+    (section) => !!section && typeof section.id === "string" && typeof section.title === "string"
+  );
+}
+async function loadPolicy(slug, options = {}) {
+  const url = getPolicyFileUrl(slug, "json", options.source);
+  const response = await fetch(url, { next: { revalidate: options.revalidate ?? 3600 } });
+  if (!response.ok) {
+    throw new Error(`loadPolicy: ${url} answered ${response.status}`);
+  }
+  const content = await response.json();
+  if (!isPolicyContent(content)) {
+    throw new Error(`loadPolicy: ${url} is not a policy page`);
+  }
+  return {
+    title: content.title,
+    updated: content.updated,
+    sections: content.sections.map(({ id, title }) => ({ id, title })),
+    html: content.html
+  };
+}
+export {
+  POLICIES_INDEX_URL,
+  POLICY_SITE_URL,
+  POLICY_SOURCE,
+  footerPolicies,
+  getPolicyFileUrl,
+  getPolicyPageUrl,
+  loadPolicy,
+  policies,
+  publishedPolicies
+};

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@tuwaio/docs-ui",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": false,
   "author": "Oleksandr Tkach",
   "license": "Apache-2.0",
-  "description": "Shared UI of the TUWA documentation sites: Nextra navbar and footer, remote logo, theme switcher, background effects and styles.",
+  "description": "Shared UI of the TUWA documentation sites: Nextra navbar and footer, remote logo, theme switcher, background effects, policy pages and styles.",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",