@supportpages.io/wtfm 0.0.0-stage → 0.3.0

package/dist/repository-benefits.js

@@ -0,0 +1,64 @@
+import path from 'node:path';
+import { z } from 'zod';
+import { ReminderJournal, claimDelivery, defaultConfigDir, reminderStateSchema, selectBenefit } from './reminders.js';
+export const repositoryInvitationSchema = z.object({ id: z.string(), message: z.string(), connect_url: z.url() });
+export const repositoryBenefits = [
+    { id: 'agent_allowance', category: 'usage', message: 'Keep your coding-agent allowance for building your product. Generate future articles using your SupportPages.io plan’s AI allowance.' },
+    { id: 'documentation_allowance', category: 'usage', message: 'Let SupportPages.io spend its AI allowance on your documentation, while you keep your coding-agent usage for your product.' },
+    { id: 'next_article_allowance', category: 'usage', message: 'Your next article can use your SupportPages.io plan’s AI allowance. Connect your repository to generate it in the web app.' },
+    { id: 'elapsed_generation', category: 'hosted', message: 'This draft was ready in {duration}. Next time, let SupportPages.io handle generation without keeping your local coding agent running.' },
+    { id: 'web_generation', category: 'hosted', message: 'Create your next article directly in SupportPages.io, without opening a local coding-agent session.' },
+    { id: 'background_generation', category: 'hosted', message: 'Let SupportPages.io generate articles in the background while you carry on building your product.' },
+    { id: 'topic_discovery', category: 'discovery', message: 'Not sure what to document next? SupportPages.io can suggest articles based on your product’s features.' },
+    { id: 'coverage_gaps', category: 'discovery', message: 'Discover features your help centre doesn’t cover yet, with suggestions based on your repository.' },
+    { id: 'section_suggestions', category: 'organisation', message: 'Give your help centre a clearer structure with section suggestions based on your product.' },
+    { id: 'organisation', category: 'organisation', message: 'Help customers find the right answer by organising your articles into help-centre sections.' },
+    { id: 'change_tracking', category: 'maintenance', message: 'Turn merged pull requests into suggestions for documentation your customers might need.' },
+    { id: 'weekly_analysis', category: 'maintenance', message: 'Prefer a regular catch-up? Connect your repository and choose weekly analysis of merged pull requests.' },
+    { id: 'maintenance', category: 'maintenance', message: 'Spot articles that need updating by comparing your documentation with your code.' },
+    { id: 'automatic_drafts', category: 'automation', message: 'Choose automatic draft generation to turn article suggestions into drafts you can review before publishing.' },
+    { id: 'batch_generation', category: 'automation', message: 'Work through your documentation backlog by generating multiple suggested articles from the web app.' },
+];
+/** The exact paragraph the agent shows after a draft review link: the benefit, then the link. */
+export const repositoryShowText = (invitation) => `${invitation.message} [Connect repository](${invitation.connect_url})`;
+export function articleDuration(start, ready) {
+    if (!start || !ready)
+        return;
+    const minutes = Math.floor((Date.parse(ready) - Date.parse(start)) / 60_000);
+    if (!Number.isFinite(minutes) || minutes < 5)
+        return;
+    const hours = Math.floor(minutes / 60), remainder = minutes % 60;
+    return hours ? `${hours} hour${hours === 1 ? '' : 's'}${remainder ? ` ${remainder} minute${remainder === 1 ? '' : 's'}` : ''}` : `${minutes} minutes`;
+}
+const stateSchema = reminderStateSchema(repositoryInvitationSchema);
+/** Device-local preferences and deduplication, shared by all checkouts of a help centre. */
+export class RepositoryReminders {
+    journal;
+    constructor(configDir = defaultConfigDir()) {
+        this.journal = new ReminderJournal(path.join(configDir, 'repository-reminders'), stateSchema);
+    }
+    transaction(origin, projectId, operation) {
+        return this.journal.transaction([new URL(origin).origin, projectId], operation);
+    }
+    preference(origin, projectId, enabled) {
+        return this.transaction(origin, projectId, state => {
+            if (enabled !== undefined)
+                state.enabled = enabled;
+            return { enabled: state.enabled, api_origin: origin, project_id: projectId, scope: 'help_centre_on_this_device' };
+        });
+    }
+    complete(input) {
+        return this.transaction(input.origin, input.projectId, state => {
+            if (!claimDelivery(state, input.articleId))
+                return;
+            if (!state.enabled || (state.count - 1) % 3 !== 0 || input.connection?.state !== 'not_connected')
+                return;
+            const duration = articleDuration(input.firstWriterStartedAt, input.readyAt);
+            const benefit = selectBenefit(state, repositoryBenefits.filter(benefit => benefit.id !== 'elapsed_generation' || duration));
+            const invitation = { id: benefit.id, message: benefit.message.replace('{duration}', duration ?? ''), connect_url: input.connection.connect_url };
+            state.articles[input.articleId] = invitation;
+            return invitation;
+        });
+    }
+}
+//# sourceMappingURL=repository-benefits.js.map

package/dist/repository-benefits.js.map

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

package/dist/run-update.d.ts

@@ -0,0 +1,17 @@
+import type { Bridge } from './bridge.js';
+/** Keep the MCP acknowledgement small; the complete run stays available in status. */
+export declare function runUpdateAcknowledgement(run: Awaited<ReturnType<Bridge['updateRun']>>, event: 'started' | 'failed' | 'interrupted' | 'cancelled'): {
+    instructions?: string | undefined;
+    recovery?: string | undefined;
+    synchronization_error?: string | undefined;
+    error?: {
+        code: string;
+        message: string;
+    } | undefined;
+    run_id: string;
+    phase: "published" | "failed" | "prepared" | "cancelled" | "interrupted" | "writing" | "finalizing" | "uploading" | "upload_failed" | "ready_for_review" | "saved";
+    execution_mode: "background" | "foreground" | undefined;
+    editor_url: string | null;
+    message: string;
+};
+export declare function runUpdateText(value: unknown): string;

package/dist/run-update.js

@@ -0,0 +1,27 @@
+import { fail } from './errors.js';
+/** Keep the MCP acknowledgement small; the complete run stays available in status. */
+export function runUpdateAcknowledgement(run, event) {
+    if (!run)
+        fail('invalid_run', 'The updated run could not be read. Check supportpages_status.');
+    return {
+        run_id: run.run_id,
+        phase: run.phase,
+        execution_mode: run.execution_mode,
+        editor_url: run.editor_url,
+        message: event === 'started' ? `Writer started in ${run.execution_mode}.` : `Writer marked as ${event}.`,
+        ...(run.error ? { error: run.error } : {}),
+        ...(run.synchronization_error ? { synchronization_error: run.synchronization_error } : {}),
+        ...(run.recovery ? { recovery: run.recovery } : {}),
+        ...(run.instructions ? { instructions: run.instructions } : {}),
+    };
+}
+export function runUpdateText(value) {
+    const result = value;
+    return [result.message,
+        ...(!result.editor_url ? ['No confirmed article link is available yet.'] : []),
+        ...(result.error ? [`${result.error.code}: ${result.error.message}`] : []),
+        ...(result.synchronization_error ? [`Preview synchronization problem: ${result.synchronization_error}`] : []),
+        result.recovery, result.instructions,
+    ].filter(Boolean).join('\n');
+}
+//# sourceMappingURL=run-update.js.map

package/dist/run-update.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-update.js","sourceRoot":"","sources":["../src/run-update.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAEnC,sFAAsF;AACtF,MAAM,UAAU,wBAAwB,CAAC,GAA6C,EAAE,KAAyD;IAC/I,IAAI,CAAC,GAAG;QAAE,IAAI,CAAC,aAAa,EAAE,+DAA+D,CAAC,CAAC;IAC/F,OAAO;QACL,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,cAAc,EAAE,GAAG,CAAC,cAAc;QAClC,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,OAAO,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,qBAAqB,GAAG,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC,oBAAoB,KAAK,GAAG;QACxG,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1C,GAAG,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC,CAAC,EAAE,qBAAqB,EAAE,GAAG,CAAC,qBAAqB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1F,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnD,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,GAAG,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChE,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,MAAM,MAAM,GAAG,KAAoD,CAAC;IACpE,OAAO,CAAC,MAAM,CAAC,OAAO;QACpB,GAAG,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,6CAA6C,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9E,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1E,GAAG,CAAC,MAAM,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,oCAAoC,MAAM,CAAC,qBAAqB,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7G,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,YAAY;KACrC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC"}