spug-sms

Spug SMS integration

Help Codex write Spug SMS integration code in an existing project. First check the language, HTTP client, configuration approach, and testing conventions used by the project, then read references/api.md; prefer reusing existing dependencies and code patterns.

Integration process

1. Confirm whether the user wants to integrate SMS sending, SMS status query, or SMS history query; implement only the capabilities actually needed, and do not extend to other channels such as email.
2. Find the project's existing HTTP client, configuration reading, error handling, and testing approach, and do not create unnecessary new abstractions or dependencies.
3. Put the template code or trusted template URL and the query token into environment variables or the project's existing secret system; do not write them into source code, examples, logs, or commits; do not accept arbitrary URLs passed in by business requests.
4. By default, design the send function to receive and always send to、name、code、number. Only when the project maintains a "template → required variables" configuration should fields be selected based on template metadata.
5. Correctly distinguish between "API accepted successfully" and "channel processed successfully": after the send API returns code: 200 , save request_id; when the final result is needed, then call the status query API.
6. Use the project's existing testing tools to simulate HTTP responses, covering at least successful responses and API errors; tests must not actually send SMS messages.

Implementation constraints

• The send API supports both POST and GET. By default, use POST https://push.spug.cc/sms/{template_code} and send JSON; use the GET query parameter form only when the project's existing conventions or the calling environment clearly require it.
• GET parameters must be encoded by the HTTP client; do not concatenate them manually; sensitive dynamic values such as phone numbers and verification codes will enter the URL, so the complete URL must not be logged.
• Validate before sending:to every phone number in it must be 11 digits,name must be 1–10 Chinese characters, English letters, or digits,code must be 4–6 English letters or digits,number must be a valid duration expressed as digits or Chinese numerals.
• Use English commas to separate multiple phone numbers, with a maximum of 5 per request. Unless the project already has batch processing conventions, do not additionally implement queues, retryers, or an SDK wrapper layer.
• The template code represents the corresponding user without requiring a separate login, and must be protected as a credential. Whether GET or POST is used, the complete request URL containing the template code must not be output in logs.
• Use a separate tokenfor status and history queries; do not mistakenly use the template code.
• Use interval queries for pending, sending, or under review statuses to avoid tight polling, and follow the project's existing task mechanism.
• When querying history, always pass type: "sms", and process only SMS records within the last 30 calendar days.

Output code

Directly modify the user's project or provide the minimal code that matches its language and framework conventions. Explain the environment variables that need to be configured, function parameters, return values, and error behavior. Unless the user explicitly requests it, do not execute real send requests.