QR for Agent

Instructions

Implementation Reference

• src/modules/qr/qr.service.ts:361-444 (handler)

  Implementation of bulkCreateQrCodes service function.

  export async function bulkCreateQrCodes(
    items: CreateQrInput[],
    apiKeyId: number,
    plan: Plan = "free"
  ) {
    // Check plan quota upfront (all-or-nothing)
    const limits = PLAN_LIMITS[plan];
    if (limits.maxQrCodes !== Infinity) {
      const [{ total }] = db
        .select({ total: count() })
        .from(qrCodes)
        .where(eq(qrCodes.apiKeyId, apiKeyId))
        .all();
  
      const remaining = limits.maxQrCodes - total;
      if (items.length > remaining) {
        return {
          error: "QR_CODE_LIMIT_REACHED" as const,
          limit: limits.maxQrCodes,
          existing: total,
          requested: items.length,
          remaining,
        };
      }
    }
  
    const customDomain = getCustomDomain(apiKeyId);
    const results = [];
    for (const input of items) {
      const shortId = nanoid(config.shortId.length);
      const format = input.format || "svg";
      const shortUrl = buildShortUrl(shortId, customDomain);
      const type = input.type || "url";
  
      let targetUrl: string;
      let typeData: string | null = null;
  
      const typeDataMap: Record<string, unknown> = {
        vcard: input.vcard_data, wifi: input.wifi_data, email: input.email_data,
        sms: input.sms_data, phone: input.phone_data, event: input.event_data,
        text: input.text_data, location: input.location_data, social: input.social_data,
        app_store: input.app_store_data,
      };
  
      if (type === "url") {
        targetUrl = input.target_url!;
      } else {
        typeData = JSON.stringify(typeDataMap[type]);
        targetUrl = shortUrl;
      }
  
      const qrContent = getQrContent(type, shortUrl, typeData);
      const styleOptions = buildStyleOptions(input);
      const imageData = await renderQrCode(qrContent, format, styleOptions);
  
      const inserted = db
        .insert(qrCodes)
        .values({
          shortId,
          targetUrl,
          label: input.label || null,
          format,
          styleOptions: styleOptions ? JSON.stringify(styleOptions) : null,
          apiKeyId,
          type,
          typeData,
          expiresAt: type === "url" ? (input.expires_at || null) : null,
          scheduledUrl: type === "url" ? (input.scheduled_url || null) : null,
          scheduledAt: type === "url" ? (input.scheduled_at || null) : null,
          utmParams: type === "url" && input.utm_params ? JSON.stringify(input.utm_params) : null,
          gtmContainerId: type === "url" ? (input.gtm_container_id || null) : null,
          redirectRules: type === "url" && input.redirect_rules ? JSON.stringify(input.redirect_rules) : null,
        })
        .returning()
        .get();
  
      results.push({
        ...formatQrResponse(inserted, customDomain),
        image_data: imageData,
      });
    }
  
    return { created: results.length, items: results };
  }

• packages/mcp/src/tools.ts:208-235 (registration)

  Registration and definition of the bulk_create_qr_codes MCP tool.

  bulk_create_qr_codes: {
    description:
      "Create multiple QR codes in a single request (up to 50). Each item supports the same options as create_qr_code. The quota check is all-or-nothing: if the batch would exceed your plan limit, no QR codes are created. Ideal for generating QR codes for product catalogs, event lists, or batch operations.",
    inputSchema: z.object({
      items: z
        .array(
          z.object({
            target_url: z.string().url().describe("The destination URL."),
            label: z.string().optional().describe("Optional label."),
            format: z.enum(["svg", "png"]).default("svg").describe("Image format."),
            foreground_color: z.string().regex(/^#[0-9A-Fa-f]{6}$/).optional().describe("Hex color for dots."),
            background_color: z.string().regex(/^#[0-9A-Fa-f]{6}$/).optional().describe("Hex color for background."),
            dot_style: z.enum(["square", "rounded", "dots", "classy-rounded"]).optional().describe("Dot shape."),
            corner_style: z.enum(["square", "extra-rounded", "dot"]).optional().describe("Corner shape."),
            logo_url: z.string().optional().describe("Logo URL or data URI."),
            expires_at: z.string().optional().describe("ISO 8601 expiration date."),
            scheduled_url: z.string().url().optional().describe("Replacement URL activated at scheduled_at."),
            scheduled_at: z.string().optional().describe("ISO 8601 activation date for scheduled_url."),
          })
        )
        .min(1)
        .max(50)
        .describe("Array of QR codes to create. Max 50 per request."),
    }),
    handler: async (input: Record<string, unknown>) => {
      return apiRequest("/api/qr/bulk", { method: "POST", body: input });
    },
  },