update_qurl

Instructions

Implementation Reference

• src/tools/update-qurl.ts:53-77 (handler)

  The updateQurlTool factory function that returns the tool definition with a handler that parses input via refined schema, calls client.updateQURL(), and returns the result as JSON text content.

  export function updateQurlTool(client: IQURLClient) {
    return {
      name: "update_qurl",
      description:
        "Update a qURL - extend expiration, set an absolute expiry, update tags, or change the description. " +
        "Accepts either a resource ID (r_ prefix) or qURL display ID (q_ prefix). " +
        "Do not provide both extend_by and expires_at. At least one update field is required.",
      // Base shape for MCP tool registration; refinements run in the handler
      inputSchema: updateQurlBaseSchema,
      handler: async (raw: z.infer<typeof updateQurlBaseSchema>) => {
        const parsed = updateQurlSchema.safeParse(raw);
        if (!parsed.success) return zodErrorToToolResult(parsed.error);
        const { resource_id, ...body } = parsed.data;
        const result = await client.updateQURL(resource_id, body);
        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify(result.data),
            },
          ],
        };
      },
    };
  }

• src/tools/update-qurl.ts:17-31 (schema)

  Base Zod schema for update_qurl input — defines resource_id, extend_by, expires_at, tags, and description fields.

  export const updateQurlBaseSchema = z.object({
    resource_id: resourceIdSchema("update"),
    extend_by: z.string().min(1).optional().describe('Duration to extend by (e.g., "24h", "7d"). Mutually exclusive with expires_at.'),
    expires_at: z.string().datetime().optional().describe("Absolute expiration timestamp (RFC 3339). Mutually exclusive with extend_by."),
    tags: z
      .array(tagSchema)
      .max(10)
      .optional()
      .describe("Replace all tags on this resource (max 10 tags, each 1-50 chars)"),
    description: z
      .string()
      .max(500)
      .optional()
      .describe("Replace the resource description (max 500 chars)"),
  });

• src/tools/update-qurl.ts:33-51 (schema)

  Refined schema that adds cross-field validation: extend_by/expires_at mutual exclusivity and requirement that at least one update field is present.

  export const updateQurlSchema = updateQurlBaseSchema
    .refine((data) => !(data.extend_by && data.expires_at), {
      message: "Provide either extend_by or expires_at, not both",
    })
    .refine(
      // Use `!== undefined` rather than truthy checks so the API's "clear"
      // semantics work: the spec documents `description: ""` and `tags: []`
      // as valid payloads that clear the field. A plain `||` would reject
      // both because empty string is falsy in JS.
      (data) =>
        data.extend_by !== undefined ||
        data.expires_at !== undefined ||
        data.tags !== undefined ||
        data.description !== undefined,
      {
        message:
          "At least one update field (extend_by, expires_at, tags, or description) is required",
      },
    );

• src/server.ts:46-54 (registration)

  updateQurlTool is imported and added to the toolFactories array, then registered via server.tool() in the registration loop (lines 51-54).

    updateQurlTool,
    mintLinkTool,
    batchCreateTool,
  ] satisfies ToolFactory[];
  
  for (const factory of toolFactories) {
    const tool = factory(client);
    server.tool(tool.name, tool.description, tool.inputSchema.shape, tool.handler);
  }

• src/tools/_shared.ts:34-42 (helper)

  resourceIdSchema helper used by updateQurlBaseSchema to validate the resource_id parameter.

  export function resourceIdSchema(verb: string) {
    return z
      .string()
      .min(1)
      .describe(
        `The resource ID (r_ prefix) or qURL display ID (q_ prefix) to ${verb}. ` +
          "If a q_ ID is passed, the API resolves it to the parent resource automatically.",
      );
  }