@reforma/types 0.1.0 → 0.1.2

package/dist/index.js

@@ -343,7 +343,8 @@ const DEFAULT_PROJECT_SETTINGS = {
 		defaultPageTitle: "",
 		defaultMetaDescription: "",
 		faviconUrl: null,
-		indexingEnabled: true
+		indexingEnabled: true,
+		analyticsEnabled: true
 	},
 	pendingPublish: false
 };

package/package.json

@@ -2,7 +2,7 @@
     "name": "@reforma/types",
     "author": "Reforma, Inc. <dev@reforma.ai>",
     "description": "Shared types between Reforma apps/packages",
-    "version": "0.1.0",
+    "version": "0.1.2",
     "license": "UNLICENSED",
     "repository": {
         "type": "git",

package/src/api/composer-drafts.ts

@@ -0,0 +1,47 @@
+/** Public file id from `POST /files/public/presign`. The API fills url and name from that row. */
+export type CreateComposerDraftAttachment = {
+    id: string;
+};
+
+/** What a marketing site sends before redirecting to `/new?draft=`. */
+export type CreateComposerDraft = {
+    prompt: string;
+    planMode?: boolean;
+    attachments?: CreateComposerDraftAttachment[];
+    /** When the visitor submitted. ISO 8601. The API stamps now when this is omitted. */
+    createdAt?: string;
+};
+
+export type ComposerDraftAttachment = {
+    id: string;
+    url: string;
+    filename: string;
+    mediaType: string;
+    size: number;
+};
+
+/** Stored handoff. Attachments are public uploads, not client-supplied URLs. */
+export type ComposerDraft = {
+    prompt: string;
+    planMode: boolean;
+    attachments: ComposerDraftAttachment[];
+    /** ISO 8601 submit time. */
+    createdAt: string;
+    /** Set once this handoff has created a project. Later visits open that project. */
+    projectId?: number;
+};
+
+/** Remember the project a handoff already created. The first id wins. */
+export type ClaimComposerDraftProject = {
+    projectId: number;
+};
+
+/** Result of claiming. `fresh` is true only for the call that recorded the project. */
+export type ClaimedComposerDraftProject = {
+    projectId: number;
+    fresh: boolean;
+};
+
+export type CreateComposerDraftResponse = {
+    id: string;
+};

package/src/api/index.ts

@@ -1,6 +1,7 @@
 export * from './auth';
 export * from './billing';
 export * from './chat';
+export * from './composer-drafts';
 export * from './file';
 export * from './files/buffer-upload';
 export * from './files/file-owner-type.enum';

package/src/api/projects/analytics/analytics-collect.ts

@@ -0,0 +1,15 @@
+/** Body for public `POST /analytics/collect`. */
+export interface AnalyticsCollect {
+    /** Project write key baked into `REFORMA_ANALYTICS_KEY`. */
+    key: string;
+    /** Full page URL or path; server extracts path and UTM. */
+    url: string;
+    referrer?: string;
+    /**
+     * Event name. Omit or `pageview` for a traffic pageview; any other name is a
+     * custom event (goal conversion).
+     */
+    name?: string;
+    /** Optional string props for custom events (ignored for pageviews). */
+    props?: Record<string, string>;
+}

package/src/api/projects/analytics/analytics-summary.ts

@@ -0,0 +1,93 @@
+/** Aggregated traffic for a project date range. */
+export interface AnalyticsSummary {
+    uniqueVisitors: number;
+    totalVisits: number;
+    totalPageviews: number;
+    viewsPerVisit: number;
+    bounceRate: number;
+    /** Mean visit duration in seconds. */
+    visitDuration: number;
+    timeseries: AnalyticsTimeseriesPoint[];
+    topPages: AnalyticsBreakdownRow[];
+    entryPages: AnalyticsBreakdownRow[];
+    exitPages: AnalyticsBreakdownRow[];
+    /** Referrer host or utm_source (Direct when neither). */
+    topSources: AnalyticsBreakdownRow[];
+    /** Coarse: Direct | Referral | Campaign. */
+    channels: AnalyticsBreakdownRow[];
+    /** utm_medium values. Pageviews without a medium are omitted. */
+    mediums: AnalyticsBreakdownRow[];
+    campaigns: AnalyticsBreakdownRow[];
+    countries: AnalyticsBreakdownRow[];
+    browsers: AnalyticsBreakdownRow[];
+    operatingSystems: AnalyticsBreakdownRow[];
+    devices: AnalyticsBreakdownRow[];
+    /**
+     * Custom events in the range (no registry). Capped at the API goals limit;
+     * when `goalsTruncated` is true more names exist than were returned.
+     */
+    goals: AnalyticsGoalRow[];
+    goalsTruncated: boolean;
+    comparison?: AnalyticsComparison;
+}
+
+export interface AnalyticsTimeseriesPoint {
+    /** ISO date (day) or hour bucket start. */
+    t: string;
+    visitors: number;
+    pageviews: number;
+    visits: number;
+    bounceRate: number;
+    /** Mean visit duration in seconds for the bucket. */
+    visitDuration: number;
+}
+
+export interface AnalyticsBreakdownRow {
+    name: string;
+    visitors: number;
+    pageviews: number;
+}
+
+/** One custom event name aggregated as a conversion goal. */
+export interface AnalyticsGoalRow {
+    name: string;
+    /** Distinct visitors who fired this event at least once. */
+    visitors: number;
+    /** Total event firings. */
+    conversions: number;
+    /**
+     * Converters / pageview unique visitors, clamped to at most 1. Zero when
+     * there were no pageview visitors in the range (event-only traffic).
+     */
+    conversionRate: number;
+    /**
+     * Top prop pairs as `key=value` rows. `pageviews` and `visitors` are firing
+     * counts for that pair (not distinct people across combinations).
+     */
+    props: AnalyticsBreakdownRow[];
+}
+
+/** Distinct visitors with a pageview in the last few minutes. */
+export interface AnalyticsRealtime {
+    currentVisitors: number;
+}
+
+export type AnalyticsPeriod = 'today' | 'yesterday' | '24h' | '7d' | '30d' | '90d' | 'month' | 'lastMonth';
+
+export interface AnalyticsComparisonQuery {
+    compare: 'previous';
+    period?: AnalyticsPeriod;
+    timeZone?: string;
+}
+
+export type AnalyticsMetrics = Pick<AnalyticsSummary,
+    'uniqueVisitors' | 'totalVisits' | 'totalPageviews' | 'viewsPerVisit' | 'bounceRate' | 'visitDuration'
+>;
+
+export interface AnalyticsComparison {
+    from: string;
+    to: string;
+    status: 'available' | 'outside_retention' | 'error';
+    /** Null means unavailable; an available period with no traffic has zero-valued metrics. */
+    metrics: AnalyticsMetrics | null;
+}

package/src/api/projects/analytics/index.ts

@@ -0,0 +1,12 @@
+export type { AnalyticsCollect } from './analytics-collect';
+export type {
+    AnalyticsBreakdownRow,
+    AnalyticsComparison,
+    AnalyticsComparisonQuery,
+    AnalyticsGoalRow,
+    AnalyticsMetrics,
+    AnalyticsPeriod,
+    AnalyticsRealtime,
+    AnalyticsSummary,
+    AnalyticsTimeseriesPoint,
+} from './analytics-summary';

package/src/api/projects/env-vars/project-env-var.ts

@@ -10,6 +10,11 @@ export interface ProjectEnvVar {
     key: string;
     /** Covers both environments. */
     isSecret: boolean;
+    /**
+     * Set by Reforma (public hostname, default title, and the other publish
+     * keys). Present on list reads. Not stored, and writes reject the key.
+     */
+    managed?: boolean;
     /** Always set — a variable cannot exist without a production value. */
     production: ProjectEnvVarValue;
     /** `null` means development inherits the production value. */

package/src/api/projects/index.ts

@@ -1,5 +1,6 @@
 export * from './admin-oauth-client';
 export * from './admin-project';
+export * from './analytics/index';
 export * from './create-project';
 export * from './deployments/index';
 export * from './domains/index';

package/src/api/projects/project.ts

@@ -26,6 +26,8 @@ export interface ProjectSettings {
         defaultMetaDescription: string;
         faviconUrl: string | null;
         indexingEnabled: boolean;
+        /** First-party pageview collection. Default on; publish bakes `REFORMA_ANALYTICS`. */
+        analyticsEnabled: boolean;
     };
     editor?: ProjectEditorSettings;
     /** SEO or env changed since the last successful publish. */
@@ -41,6 +43,7 @@ export const DEFAULT_PROJECT_SETTINGS: ProjectSettings = {
         defaultMetaDescription: '',
         faviconUrl: null,
         indexingEnabled: true,
+        analyticsEnabled: true,
     },
     pendingPublish: false,
 };

package/src/sandbox/git/version.ts

@@ -33,7 +33,7 @@ export type VersionListChanges = {
  * Optional `versionChanges` patches the version list in the same event.
  */
 export type VersionStatus = {
-    /** Version on HEAD (`reforma-version` trailer), or null when unversioned. */
+    /** Version on HEAD or its nearest ancestor across service commits; null when unversioned. */
     currentVersion: string | null;
     /** Working tree has uncommitted changes. */
     uncommitted: boolean;

package/src/sandbox/process.ts

@@ -18,6 +18,11 @@ export interface CommandSpec {
      * The sandbox will manage bounded rolling segments (e.g. `${logFile}.0.jsonl`).
      */
     logFile?: string;
+    /**
+     * When true with `logFile`, open the JSONL for append instead of truncating on start.
+     * Used for session channels (install) that accumulate across runs.
+     */
+    appendLog?: boolean;
     /** Automatically remove executed command from registry after TTL. Default true. */
     autoClean?: boolean;
 }

package/src/sandbox/tools/choose-design-direction.ts

@@ -2,7 +2,7 @@
 
 export type ChooseDesignDirectionVariant = {
     id: string;
-    /** Short name on the card, in the user's language. */
+    /** Short English name on the card. */
     label: string;
     /** Optional note. For a generated preview, the English prompt. Not shown on the card. */
     description?: string;

package/src/sandbox/tools/project-env.ts

@@ -14,6 +14,8 @@ export type ProjectEnvToolListedVariable = {
     key: string;
     secret: boolean;
     developmentOverride: boolean;
+    /** Set by Reforma. Read it from the environment; do not change it. */
+    managed?: boolean;
 };
 
 export type ProjectEnvToolOutput = {