feat(latchshot): expose paid-plan continuation links (oomol-lab#155)

## Summary

- pass through the three stable paid-plan continuation URLs returned by
Latchshot's `GET /v1/usage`
- publish those URLs in the `get_usage` output schema
- state explicitly that `get_usage` never initiates payment or an
upgrade
- reject missing or malformed continuation fields instead of returning
an output that violates the action schema

## Why

I maintain Latchshot. Its authenticated usage response now includes
links to the public plan comparison, the human paid-plan request form,
and the authenticated request API documentation. The accepted Open
Connector provider currently drops those fields.

This keeps commercial continuation discoverable to an Open Connector
user while preserving the existing boundary: `get_usage` is read-only,
and the provider still has no payment or plan-changing action.

## Scope and security

- no new action, endpoint, redirect, credential behavior, or egress
destination
- the provider still calls only the fixed `https://latchshot.fly.dev`
origin
- no payment information is read or stored
- output remains bounded JSON from the existing usage request

## Validation

- `npm run fix-check`
- `npm run generate:catalog` — 1,093 apps / 11,177 actions
- focused Latchshot tests: 10/10 passed
- full suite: 700/700 passed across 76 files
- `git diff --check`

Co-authored-by: Andy Lyu <andy@example.com>

Author: BaiqingL

src/providers/latchshot/actions.ts

@@ -149,13 +149,20 @@ const upgradeRequestSchema = s.object(
   { required: ["id", "keyId", "requestedPlan", "note", "status", "createdAt", "updatedAt"] },
 );
 
+const usageLinksSchema = s.requiredObject("Owner-managed paid-plan continuation links.", {
+  plans: s.url("The public Latchshot plan comparison."),
+  requestPaidPlan: s.url("The human paid-plan request form."),
+  requestPaidPlanDocs: s.url("The authenticated paid-plan request API documentation."),
+});
+
 const usageOutputSchema = s.requiredObject("The current Latchshot plan and quota snapshot.", {
   customer: s.requiredObject("The display identity attached to the API key.", {
     name: s.nonEmptyString("The display name attached to the API key."),
     plan: planSchema,
   }),
   usage: usageSchema,
   upgradeRequest: s.nullable(upgradeRequestSchema),
+  links: usageLinksSchema,
 });
 
 export const latchshotActions: ActionDefinition[] = [
@@ -168,7 +175,8 @@ export const latchshotActions: ActionDefinition[] = [
   }),
   defineProviderAction(service, {
     name: "get_usage",
-    description: "Read the current Latchshot plan, successful-render quota, reset time, and upgrade-request status.",
+    description:
+      "Read the current Latchshot plan, successful-render quota, reset time, upgrade-request status, and owner-managed paid-plan links. This action never initiates payment or an upgrade.",
     inputSchema: s.object("No input is required to read usage for the configured API key.", {}),
     outputSchema: usageOutputSchema,
   }),

src/providers/latchshot/executors.test.ts

@@ -202,6 +202,18 @@ describe("Latchshot provider", () => {
         createdAt: "2026-07-18T00:00:00.000Z",
         updatedAt: "2026-07-19T00:00:00.000Z",
       },
+      links: usageLinks(),
+    });
+  });
+
+  it("rejects a usage response without owner-managed continuation links", async () => {
+    const payload = usagePayload();
+    delete payload.links;
+    const context = createContext([], Response.json(payload));
+
+    await expect(latchshotActionHandlers.get_usage!({}, context)).rejects.toMatchObject({
+      status: 502,
+      message: "Latchshot usage response is missing continuation links.",
     });
   });
 
@@ -278,6 +290,7 @@ function usagePayload(): Record<string, unknown> {
       updatedAt: null,
     },
     upgradeRequest: null,
+    links: usageLinks(),
   };
 }
 
@@ -307,5 +320,14 @@ function forwardCompatibleUsagePayload(): Record<string, unknown> {
       createdAt: "2026-07-18T00:00:00.000Z",
       updatedAt: "2026-07-19T00:00:00.000Z",
     },
+    links: usageLinks(),
+  };
+}
+
+function usageLinks(): Record<string, string> {
+  return {
+    plans: "https://latchshot.fly.dev/#pricing",
+    requestPaidPlan: "https://latchshot.fly.dev/#upgrade",
+    requestPaidPlanDocs: "https://latchshot.fly.dev/docs.md#request-a-paid-plan",
   };
 }

src/providers/latchshot/executors.ts

@@ -236,6 +236,7 @@ function normalizeUsagePayload(payload: unknown): {
   customer: { name: string; plan: string };
   usage: Record<string, unknown>;
   upgradeRequest: Record<string, unknown> | null;
+  links: Record<string, string>;
 } {
   const record = requireObject(payload, "Latchshot usage response must be an object.");
   const customer = requireObject(record.customer, "Latchshot usage response is missing customer data.");
@@ -261,6 +262,16 @@ function normalizeUsagePayload(payload: unknown): {
         usage.updatedAt === null ? null : requiredString(usage.updatedAt, "usage.updatedAt", invalidResponseError),
     },
     upgradeRequest: normalizeUpgradeRequest(record.upgradeRequest),
+    links: normalizeUsageLinks(record.links),
+  };
+}
+
+function normalizeUsageLinks(value: unknown): Record<string, string> {
+  const links = requireObject(value, "Latchshot usage response is missing continuation links.");
+  return {
+    plans: requiredString(links.plans, "links.plans", invalidResponseError),
+    requestPaidPlan: requiredString(links.requestPaidPlan, "links.requestPaidPlan", invalidResponseError),
+    requestPaidPlanDocs: requiredString(links.requestPaidPlanDocs, "links.requestPaidPlanDocs", invalidResponseError),
   };
 }