@marinoscar/platform-contract 0.1.0-next.3 → 0.1.0-next.4

package/dist/cjs/onboarding/schemas.d.ts

@@ -0,0 +1,360 @@
+import { z } from 'zod';
+import { ONBOARDING_AUDIENCES, ONBOARDING_STATUSES, ONBOARDING_TIERS } from './constants.js';
+/**
+ * The entries of the original two-audience enum.
+ *
+ * @deprecated The audience vocabulary is open; see `onboardingAudienceSchema`.
+ * @stability experimental
+ */
+export type OnboardingAudienceEnum = {
+    [K in (typeof ONBOARDING_AUDIENCES)[number]]: K;
+};
+/**
+ * The entries of the tier enum.
+ *
+ * @stability experimental
+ */
+export type OnboardingTierEnum = {
+    [K in (typeof ONBOARDING_TIERS)[number]]: K;
+};
+/**
+ * The entries of the status enum.
+ *
+ * @stability experimental
+ */
+export type OnboardingStatusEnum = {
+    [K in (typeof ONBOARDING_STATUSES)[number]]: K;
+};
+/**
+ * The entries of the `refresh` query enum.
+ *
+ * @stability experimental
+ */
+export type OnboardingRefreshEnum = {
+    /** Bypass the Doctor's cache. */
+    true: 'true';
+    /** Use it. */
+    false: 'false';
+};
+/**
+ * A step's audience: an id matching `ONBOARDING_AUDIENCE_ID_PATTERN`. The
+ * built-ins are `admin`, `user` and `org_admin`; an app registers more with
+ * `registerOnboardingAudience`.
+ *
+ * @stability experimental
+ */
+export declare const onboardingAudienceSchema: z.ZodString;
+/**
+ * A step's tier.
+ *
+ * @stability experimental
+ */
+export declare const onboardingTierSchema: z.ZodEnum<OnboardingTierEnum>;
+/**
+ * A step's derived status.
+ *
+ * @stability experimental
+ */
+export declare const onboardingStatusSchema: z.ZodEnum<OnboardingStatusEnum>;
+/**
+ * The raw `refresh` query value.
+ *
+ * @stability experimental
+ */
+export declare const onboardingRefreshSchema: z.ZodEnum<OnboardingRefreshEnum>;
+/**
+ * The fields of the stored `onboarding` namespace, as a zod shape. An app
+ * extends the namespace with its own fields through `extendOnboardingSettings`
+ * in `@marinoscar/platform-api/onboarding`; it never edits this shape.
+ *
+ * @stability experimental
+ */
+export declare const onboardingSettingsShape: {
+    /** The welcome dialog was closed, by any route. */
+    welcomeSeenAt: z.ZodOptional<z.ZodString>;
+    /** The user hid the Get started checklist. */
+    checklistDismissedAt: z.ZodOptional<z.ZodString>;
+    /** An administrator hid the Setup guide prompt. */
+    adminDismissedAt: z.ZodOptional<z.ZodString>;
+    /** Ids of registered, skippable steps the user chose to skip. */
+    skipped: z.ZodOptional<z.ZodArray<z.ZodString>>;
+};
+/**
+ * The stored `onboarding` namespace (`user_settings.value.onboarding`).
+ * `.strict()`: an unknown key is refused, so the namespace stays closed until
+ * an app extends it.
+ *
+ * @stability experimental
+ */
+export declare const onboardingSettingsSchema: z.ZodObject<{
+    welcomeSeenAt: z.ZodOptional<z.ZodString>;
+    checklistDismissedAt: z.ZodOptional<z.ZodString>;
+    adminDismissedAt: z.ZodOptional<z.ZodString>;
+    skipped: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+/**
+ * The stored `onboarding` namespace.
+ *
+ * @stability experimental
+ */
+export type OnboardingSettings = z.infer<typeof onboardingSettingsSchema>;
+/**
+ * `onboarding` in a `PATCH /api/user-settings` body: every field optional,
+ * and an explicit `null` clears it (a shallow merge).
+ *
+ * @stability experimental
+ */
+export declare const onboardingSettingsPatchSchema: z.ZodObject<{
+    welcomeSeenAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    checklistDismissedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    adminDismissedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    skipped: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+}, z.core.$strict>;
+/**
+ * A parsed `onboarding` PATCH branch.
+ *
+ * @stability experimental
+ */
+export type OnboardingSettingsPatch = z.infer<typeof onboardingSettingsPatchSchema>;
+/**
+ * The query of `GET /api/onboarding`. `refresh` is a string enum, NOT a
+ * coerced boolean: every query parameter is a string and `Boolean('false')` is
+ * `true`.
+ *
+ * @stability experimental
+ */
+export declare const onboardingQuerySchema: z.ZodObject<{
+    refresh: z.ZodOptional<z.ZodPipe<z.ZodEnum<OnboardingRefreshEnum>, z.ZodTransform<boolean, "true" | "false">>>;
+}, z.core.$strip>;
+/**
+ * One derived step.
+ *
+ * @stability experimental
+ */
+export declare const onboardingStepSchema: z.ZodObject<{
+    id: z.ZodString;
+    audience: z.ZodString;
+    tier: z.ZodEnum<OnboardingTierEnum>;
+    status: z.ZodEnum<OnboardingStatusEnum>;
+    title: z.ZodString;
+    description: z.ZodString;
+    actionLabel: z.ZodString;
+    href: z.ZodString;
+    detail: z.ZodNullable<z.ZodString>;
+    blockedReason: z.ZodNullable<z.ZodString>;
+    skippable: z.ZodBoolean;
+    skipped: z.ZodBoolean;
+}, z.core.$strip>;
+/**
+ * One derived step.
+ *
+ * @stability experimental
+ */
+export type OnboardingStep = z.infer<typeof onboardingStepSchema>;
+/**
+ * One audience's checklist.
+ *
+ * @stability experimental
+ */
+export declare const onboardingBlockSchema: z.ZodObject<{
+    steps: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        audience: z.ZodString;
+        tier: z.ZodEnum<OnboardingTierEnum>;
+        status: z.ZodEnum<OnboardingStatusEnum>;
+        title: z.ZodString;
+        description: z.ZodString;
+        actionLabel: z.ZodString;
+        href: z.ZodString;
+        detail: z.ZodNullable<z.ZodString>;
+        blockedReason: z.ZodNullable<z.ZodString>;
+        skippable: z.ZodBoolean;
+        skipped: z.ZodBoolean;
+    }, z.core.$strip>>;
+    completed: z.ZodNumber;
+    total: z.ZodNumber;
+    requiredDone: z.ZodBoolean;
+    allResolved: z.ZodBoolean;
+}, z.core.$strip>;
+/**
+ * One audience's checklist.
+ *
+ * @stability experimental
+ */
+export type OnboardingBlock = z.infer<typeof onboardingBlockSchema>;
+/**
+ * The stored UI state as the response reports it: each platform field `null`
+ * when unset, `skipped` without ids that are no longer registered and
+ * skippable, plus any field an app added with `extendOnboardingSettings`.
+ *
+ * @stability experimental
+ */
+export declare const onboardingStateSchema: z.ZodObject<{
+    welcomeSeenAt: z.ZodNullable<z.ZodString>;
+    checklistDismissedAt: z.ZodNullable<z.ZodString>;
+    adminDismissedAt: z.ZodNullable<z.ZodString>;
+    skipped: z.ZodArray<z.ZodString>;
+}, z.core.$loose>;
+/**
+ * The stored UI state as the response reports it.
+ *
+ * @stability experimental
+ */
+export type OnboardingState = z.infer<typeof onboardingStateSchema>;
+/**
+ * The response of `GET /api/onboarding`.
+ *
+ * @stability experimental
+ */
+export declare const onboardingResponseSchema: z.ZodObject<{
+    settings: z.ZodObject<{
+        welcomeSeenAt: z.ZodNullable<z.ZodString>;
+        checklistDismissedAt: z.ZodNullable<z.ZodString>;
+        adminDismissedAt: z.ZodNullable<z.ZodString>;
+        skipped: z.ZodArray<z.ZodString>;
+    }, z.core.$loose>;
+    user: z.ZodObject<{
+        steps: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            audience: z.ZodString;
+            tier: z.ZodEnum<OnboardingTierEnum>;
+            status: z.ZodEnum<OnboardingStatusEnum>;
+            title: z.ZodString;
+            description: z.ZodString;
+            actionLabel: z.ZodString;
+            href: z.ZodString;
+            detail: z.ZodNullable<z.ZodString>;
+            blockedReason: z.ZodNullable<z.ZodString>;
+            skippable: z.ZodBoolean;
+            skipped: z.ZodBoolean;
+        }, z.core.$strip>>;
+        completed: z.ZodNumber;
+        total: z.ZodNumber;
+        requiredDone: z.ZodBoolean;
+        allResolved: z.ZodBoolean;
+    }, z.core.$strip>;
+    admin: z.ZodNullable<z.ZodObject<{
+        steps: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            audience: z.ZodString;
+            tier: z.ZodEnum<OnboardingTierEnum>;
+            status: z.ZodEnum<OnboardingStatusEnum>;
+            title: z.ZodString;
+            description: z.ZodString;
+            actionLabel: z.ZodString;
+            href: z.ZodString;
+            detail: z.ZodNullable<z.ZodString>;
+            blockedReason: z.ZodNullable<z.ZodString>;
+            skippable: z.ZodBoolean;
+            skipped: z.ZodBoolean;
+        }, z.core.$strip>>;
+        completed: z.ZodNumber;
+        total: z.ZodNumber;
+        requiredDone: z.ZodBoolean;
+        allResolved: z.ZodBoolean;
+    }, z.core.$strip>>;
+    audiences: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        steps: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            audience: z.ZodString;
+            tier: z.ZodEnum<OnboardingTierEnum>;
+            status: z.ZodEnum<OnboardingStatusEnum>;
+            title: z.ZodString;
+            description: z.ZodString;
+            actionLabel: z.ZodString;
+            href: z.ZodString;
+            detail: z.ZodNullable<z.ZodString>;
+            blockedReason: z.ZodNullable<z.ZodString>;
+            skippable: z.ZodBoolean;
+            skipped: z.ZodBoolean;
+        }, z.core.$strip>>;
+        completed: z.ZodNumber;
+        total: z.ZodNumber;
+        requiredDone: z.ZodBoolean;
+        allResolved: z.ZodBoolean;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/**
+ * The response of `GET /api/onboarding`.
+ *
+ * @stability experimental
+ */
+export type OnboardingResponse = z.infer<typeof onboardingResponseSchema>;
+/**
+ * The query of the metrics route: the cohort is the users created in the last
+ * `days` days (1 to 365, default 30).
+ *
+ * @stability experimental
+ */
+export declare const onboardingMetricsQuerySchema: z.ZodObject<{
+    days: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+/**
+ * One registered activation milestone, aggregated over the cohort.
+ *
+ * @stability experimental
+ */
+export declare const onboardingMilestoneMetricSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    windowDays: z.ZodNumber;
+    eligible: z.ZodNumber;
+    activated: z.ZodNumber;
+    activationRate: z.ZodNullable<z.ZodNumber>;
+    medianHours: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * One milestone's aggregate.
+ *
+ * @stability experimental
+ */
+export type OnboardingMilestoneMetric = z.infer<typeof onboardingMilestoneMetricSchema>;
+/**
+ * One funnel row: how many cohort users have a step done now.
+ *
+ * @stability experimental
+ */
+export declare const onboardingFunnelStepSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    completed: z.ZodNumber;
+    rate: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * One funnel row.
+ *
+ * @stability experimental
+ */
+export type OnboardingFunnelStep = z.infer<typeof onboardingFunnelStepSchema>;
+/**
+ * The response of `GET /api/admin/onboarding/metrics`: aggregates only, never
+ * a row about one user.
+ *
+ * @stability experimental
+ */
+export declare const onboardingMetricsResponseSchema: z.ZodObject<{
+    windowDays: z.ZodNumber;
+    cohortSize: z.ZodNumber;
+    milestones: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        windowDays: z.ZodNumber;
+        eligible: z.ZodNumber;
+        activated: z.ZodNumber;
+        activationRate: z.ZodNullable<z.ZodNumber>;
+        medianHours: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+    steps: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        completed: z.ZodNumber;
+        rate: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * The response of `GET /api/admin/onboarding/metrics`.
+ *
+ * @stability experimental
+ */
+export type OnboardingMetricsResponse = z.infer<typeof onboardingMetricsResponseSchema>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/cjs/onboarding/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../../src/onboarding/schemas.ts"],"names":[],"mappings":"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"}

package/dist/cjs/onboarding/schemas.js

@@ -0,0 +1,260 @@
+"use strict";
+// =============================================================================
+// The onboarding slice's wire shapes (issue #745, PP-9.3)
+// =============================================================================
+//
+// The stored `onboarding` user-settings namespace (UI state only: a step's
+// completion is DERIVED on every request, never stored), the query and
+// response of `GET /api/onboarding`, and the query and response of
+// `GET /api/admin/onboarding/metrics`. Shared by
+// `@marinoscar/platform-api/onboarding` (which wraps them as DTOs, so the
+// OpenAPI document is generated from them) and `@marinoscar/platform-web/onboarding`.
+//
+// NO `.default()` in the stored namespace: absent means "never seen, never
+// dismissed, nothing skipped".
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.onboardingMetricsResponseSchema = exports.onboardingFunnelStepSchema = exports.onboardingMilestoneMetricSchema = exports.onboardingMetricsQuerySchema = exports.onboardingResponseSchema = exports.onboardingStateSchema = exports.onboardingBlockSchema = exports.onboardingStepSchema = exports.onboardingQuerySchema = exports.onboardingSettingsPatchSchema = exports.onboardingSettingsSchema = exports.onboardingSettingsShape = exports.onboardingRefreshSchema = exports.onboardingStatusSchema = exports.onboardingTierSchema = exports.onboardingAudienceSchema = void 0;
+const zod_1 = require("zod");
+const constants_js_1 = require("./constants.js");
+/**
+ * A step's audience: an id matching `ONBOARDING_AUDIENCE_ID_PATTERN`. The
+ * built-ins are `admin`, `user` and `org_admin`; an app registers more with
+ * `registerOnboardingAudience`.
+ *
+ * @stability experimental
+ */
+exports.onboardingAudienceSchema = zod_1.z.string().regex(constants_js_1.ONBOARDING_AUDIENCE_ID_PATTERN);
+/**
+ * A step's tier.
+ *
+ * @stability experimental
+ */
+exports.onboardingTierSchema = zod_1.z.enum(constants_js_1.ONBOARDING_TIERS);
+/**
+ * A step's derived status.
+ *
+ * @stability experimental
+ */
+exports.onboardingStatusSchema = zod_1.z.enum(constants_js_1.ONBOARDING_STATUSES);
+/**
+ * The raw `refresh` query value.
+ *
+ * @stability experimental
+ */
+exports.onboardingRefreshSchema = zod_1.z.enum(['true', 'false']);
+// =============================================================================
+// The stored namespace
+// =============================================================================
+const isoDateTime = zod_1.z.string().datetime({ offset: true });
+/**
+ * The fields of the stored `onboarding` namespace, as a zod shape. An app
+ * extends the namespace with its own fields through `extendOnboardingSettings`
+ * in `@marinoscar/platform-api/onboarding`; it never edits this shape.
+ *
+ * @stability experimental
+ */
+exports.onboardingSettingsShape = {
+    /** The welcome dialog was closed, by any route. */
+    welcomeSeenAt: isoDateTime.optional(),
+    /** The user hid the Get started checklist. */
+    checklistDismissedAt: isoDateTime.optional(),
+    /** An administrator hid the Setup guide prompt. */
+    adminDismissedAt: isoDateTime.optional(),
+    /** Ids of registered, skippable steps the user chose to skip. */
+    skipped: zod_1.z.array(zod_1.z.string().min(1).max(constants_js_1.ONBOARDING_STEP_ID_MAX)).max(constants_js_1.ONBOARDING_SKIPPED_MAX).optional(),
+};
+/**
+ * The stored `onboarding` namespace (`user_settings.value.onboarding`).
+ * `.strict()`: an unknown key is refused, so the namespace stays closed until
+ * an app extends it.
+ *
+ * @stability experimental
+ */
+exports.onboardingSettingsSchema = zod_1.z.object(exports.onboardingSettingsShape).strict();
+/**
+ * `onboarding` in a `PATCH /api/user-settings` body: every field optional,
+ * and an explicit `null` clears it (a shallow merge).
+ *
+ * @stability experimental
+ */
+exports.onboardingSettingsPatchSchema = zod_1.z
+    .object({
+    /** Set when the welcome was closed; `null` clears it. */
+    welcomeSeenAt: isoDateTime.nullable().optional(),
+    /** Set when the Get started checklist was hidden; `null` clears it. */
+    checklistDismissedAt: isoDateTime.nullable().optional(),
+    /** Set when the Setup guide prompt was hidden; `null` clears it. */
+    adminDismissedAt: isoDateTime.nullable().optional(),
+    /** The skipped step ids, replacing the stored list; `null` clears it. */
+    skipped: exports.onboardingSettingsShape.skipped.unwrap().nullable().optional(),
+})
+    .strict();
+// =============================================================================
+// GET /api/onboarding
+// =============================================================================
+/**
+ * The query of `GET /api/onboarding`. `refresh` is a string enum, NOT a
+ * coerced boolean: every query parameter is a string and `Boolean('false')` is
+ * `true`.
+ *
+ * @stability experimental
+ */
+exports.onboardingQuerySchema = zod_1.z.object({
+    /** `true` bypasses the Doctor's report cache for the Doctor-backed steps. */
+    refresh: exports.onboardingRefreshSchema
+        .transform((value) => value === 'true')
+        .optional(),
+});
+/**
+ * One derived step.
+ *
+ * @stability experimental
+ */
+exports.onboardingStepSchema = zod_1.z.object({
+    /** The permanent step id (`admin.storage`, `user.profile`, `<app>.<step>`). */
+    id: zod_1.z.string(),
+    /** Who it is for. */
+    audience: exports.onboardingAudienceSchema,
+    /** How much it matters. */
+    tier: exports.onboardingTierSchema,
+    /** Derived now, never stored. */
+    status: exports.onboardingStatusSchema,
+    /** The step's title. */
+    title: zod_1.z.string(),
+    /** One sentence on what the step achieves. */
+    description: zod_1.z.string(),
+    /** The label of the step's link. */
+    actionLabel: zod_1.z.string(),
+    /** The web route where the step is completed. */
+    href: zod_1.z.string(),
+    /** A `todo` step's hint (a Doctor step: the first non-passing check's remedy); otherwise `null`. */
+    detail: zod_1.z.string().nullable(),
+    /** Why a `blocked` step cannot be done yet; otherwise `null`. */
+    blockedReason: zod_1.z.string().nullable(),
+    /** Whether the user may skip it (never for a `required` step). */
+    skippable: zod_1.z.boolean(),
+    /** The user skipped it (it is still listed, with its derived status). */
+    skipped: zod_1.z.boolean(),
+});
+/**
+ * One audience's checklist.
+ *
+ * @stability experimental
+ */
+exports.onboardingBlockSchema = zod_1.z.object({
+    /** The steps the caller can act on, in order. */
+    steps: zod_1.z.array(exports.onboardingStepSchema),
+    /** How many are `done`. */
+    completed: zod_1.z.number().int(),
+    /** How many there are. */
+    total: zod_1.z.number().int(),
+    /** Every `required` step is `done` (true when there is none). */
+    requiredDone: zod_1.z.boolean(),
+    /** Every step is `done` or skipped: the checklist has nothing left to ask. */
+    allResolved: zod_1.z.boolean(),
+});
+/**
+ * The stored UI state as the response reports it: each platform field `null`
+ * when unset, `skipped` without ids that are no longer registered and
+ * skippable, plus any field an app added with `extendOnboardingSettings`.
+ *
+ * @stability experimental
+ */
+exports.onboardingStateSchema = zod_1.z
+    .object({
+    /** When the welcome was closed, or `null`. */
+    welcomeSeenAt: zod_1.z.string().nullable(),
+    /** When the Get started checklist was hidden, or `null`. */
+    checklistDismissedAt: zod_1.z.string().nullable(),
+    /** When the Setup guide prompt was hidden, or `null`. */
+    adminDismissedAt: zod_1.z.string().nullable(),
+    /** The skipped ids that are still registered, skippable steps. */
+    skipped: zod_1.z.array(zod_1.z.string()),
+})
+    .passthrough();
+/**
+ * The response of `GET /api/onboarding`.
+ *
+ * @stability experimental
+ */
+exports.onboardingResponseSchema = zod_1.z.object({
+    /** The stored UI state. */
+    settings: exports.onboardingStateSchema,
+    /** The caller's own checklist (always present, possibly empty). */
+    user: exports.onboardingBlockSchema,
+    /** The Setup guide; non-null only for a caller holding the admin permission. */
+    admin: exports.onboardingBlockSchema.nullable(),
+    /**
+     * The checklists of every other audience the caller matches and that has at
+     * least one step for them, keyed by audience id (`org_admin`, or an app's
+     * own). Absent when there is none.
+     */
+    audiences: zod_1.z.record(exports.onboardingAudienceSchema, exports.onboardingBlockSchema).optional(),
+});
+// =============================================================================
+// GET /api/admin/onboarding/metrics
+// =============================================================================
+/**
+ * The query of the metrics route: the cohort is the users created in the last
+ * `days` days (1 to 365, default 30).
+ *
+ * @stability experimental
+ */
+exports.onboardingMetricsQuerySchema = zod_1.z.object({
+    /** The cohort window, in days. */
+    days: zod_1.z.coerce.number().int().min(1).max(constants_js_1.ONBOARDING_METRICS_DAYS_MAX).default(constants_js_1.ONBOARDING_METRICS_DAYS_DEFAULT),
+});
+/**
+ * One registered activation milestone, aggregated over the cohort.
+ *
+ * @stability experimental
+ */
+exports.onboardingMilestoneMetricSchema = zod_1.z.object({
+    /** The milestone's id. */
+    id: zod_1.z.string(),
+    /** Its label. */
+    label: zod_1.z.string(),
+    /** A user counts as activated when they reach it within this many days of sign-up. */
+    windowDays: zod_1.z.number().int(),
+    /** Cohort users created at least `windowDays` ago (their window has closed). */
+    eligible: zod_1.z.number().int(),
+    /** Eligible users who reached it within `windowDays`. */
+    activated: zod_1.z.number().int(),
+    /** `activated / eligible`; `null` when nobody is eligible. */
+    activationRate: zod_1.z.number().nullable(),
+    /** Median hours from sign-up to reaching it, over cohort users who did; one decimal; `null` when none. */
+    medianHours: zod_1.z.number().nullable(),
+});
+/**
+ * One funnel row: how many cohort users have a step done now.
+ *
+ * @stability experimental
+ */
+exports.onboardingFunnelStepSchema = zod_1.z.object({
+    /** The step's id. */
+    id: zod_1.z.string(),
+    /** The step's title. */
+    title: zod_1.z.string(),
+    /** Cohort users with the step done now. */
+    completed: zod_1.z.number().int(),
+    /** `completed / cohortSize`; `null` for an empty cohort. */
+    rate: zod_1.z.number().nullable(),
+});
+/**
+ * The response of `GET /api/admin/onboarding/metrics`: aggregates only, never
+ * a row about one user.
+ *
+ * @stability experimental
+ */
+exports.onboardingMetricsResponseSchema = zod_1.z.object({
+    /** Echo of `days`. */
+    windowDays: zod_1.z.number().int(),
+    /** Users created in the last `windowDays` days. */
+    cohortSize: zod_1.z.number().int(),
+    /** One entry per registered milestone; empty when the app registered none. */
+    milestones: zod_1.z.array(exports.onboardingMilestoneMetricSchema),
+    /** One row per user step that declares a funnel query. */
+    steps: zod_1.z.array(exports.onboardingFunnelStepSchema),
+});
+//# sourceMappingURL=schemas.js.map

package/dist/cjs/onboarding/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../../src/onboarding/schemas.ts"],"names":[],"mappings":"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"}