--- name: order-internet-service description: Discover, validate, submit, and recover a Hum internet-service order through the four transactional broadband tools. metadata: author: Hum version: "1.0.0" --- # Order internet service with Hum This skill describes Hum's broadband availability and ordering tools, their data semantics, and the requirements for submitting and recovering an order. It applies when your host chooses to use Hum. Follow your host's policies for tool selection, user interaction, information access, presentation, and authorization. Hum supports a U.S. broadband workflow with four tools: 1. `check_availability` resolves the address and returns FCC findings, live qualification, or the next clarification step. 2. `validate_order` refreshes one exact offer, collects only required order details, and returns a review. It does not create an order or contact fulfillment. 3. `create_order` records an order that the user authorized from that exact review. It normally returns before fulfillment finishes. 4. `get_order` retrieves Hum's recorded submission and fulfillment evidence, including after a response is lost. Do not skip, reorder, or merge the validation, authorization, and submission steps. ## 1. Resolve the service address Start `check_availability` with one complete U.S. service address. Include the unit when the user has supplied it. Continue an existing lookup instead of starting over: - If Hum returns address candidates, show their display values and ask the user to select one. Continue with the exact returned `candidate_id`. Add `unit` only when Hum requests it. - If Hum returns `checking`, wait at least `retry_after_seconds`, then poll with only the same `lookup_id`. - If Hum returns a current `question_set_id`, ask the returned typed questions. Submit every required answer together with that `question_set_id` and `lookup_id`. Never guess an address, unit, candidate, or answer. Do not reuse an answer with a different question set. Treat `candidate_id`, `lookup_id`, `question_set_id`, `offer_id`, and `checkout_id` as opaque values and return them unchanged only to Hum. ## 2. Interpret availability without overstating it Hum may return useful results from two sources at different times: - FCC findings are provider-reported coverage for a census block or tract. They describe reported service in an area and do not prove that the exact address is serviceable. - A live provider check may qualify an offer at the resolved address. It may still be `checking`, need information, fail, or time out while FCC findings remain useful. Present each source with its returned status, provenance, and freshness. Preserve partial results. An empty offers list, an unfinished live check, or a failed live source is not proof that no service exists. Preserve unknown prices, fees, speeds, conditions, and installation facts as unknown. Returned provider records can contain both `catalog_plans` and `offers`: - A catalog plan is informational. It cannot be selected for an order. - An executable offer has an exact server-returned `offer_id`, a qualification revision, an expiry, and `orderable_through_hum: true`. Select only an executable offer. Never manufacture an offer ID, convert a catalog plan into an offer, or substitute a similar plan. ## 3. Validate the exact offer Start `validate_order` with the returned `lookup_id` and `offer_id`. After Hum creates the draft, continue with its `checkout_id` rather than repeating the initial selection. When validation returns `required_fields`, collect only those fields. Send them together with the exact `expected_revision` requested by the current result. Do not ask for or submit card data, Social Security numbers, existing-account passwords, or payment authorization. Never invent a service PIN, date of birth, installation date, consent, or customer detail. When preferred installation dates are required, collect both `first` and `second` choices. Each choice needs an explicit date and one of these exact local-time windows: - `8:00 AM - 12:00 PM (Local Time)` - `12:00 PM - 5:00 PM (Local Time)` Use only dates the user accepts. Do not derive a second date or replace a returned field error with an invented preference. For the current fulfillment checkout contract, use only `self` or `professional` as the installation type. Record the customer’s explicit true or false choices for auto-pay and paperless billing; never turn them on silently. Explain any billing-discount conditions in the returned review. Validation can require more information, remain in progress, report field errors, report that the offer changed, or say that it is unavailable or expired. Follow the returned `next_action`: - Correct only the named field errors. - Poll only after the returned delay and with the same checkout. - If the offer changed, present the difference and obtain a fresh choice or acceptance before proceeding. - If the offer is unavailable or expired, return to availability or select another current offer. Validation is non-committing. It creates no order and sends no fulfillment request. ## 4. Present the review and obtain authorization Proceed only when validation is `ready`. Present the returned review faithfully, including every known charge, fee, promotion, condition, contract term, installation preference, and consent. Clearly label missing or unknown facts. Do not fill gaps from a catalog plan or an earlier revision. Use the host's authorization mechanism to obtain the user's commitment to that exact review. The authorization must cover the current `terms_hash`. Do not set `confirmed: true` based on an earlier approval, general shopping intent, silence, or an approval for different terms. Hum omits sensitive field values from reviews and receipts. Do not repeat sensitive values in the presentation or store them outside the host's normal handling path. ## 5. Submit once After authorization, call `create_order` with the returned `checkout_id`, `validation_token`, the same `terms_hash`, `confirmed: true`, and a stable `idempotency_key`. Keep the key stable for the same intended order. Do not reuse it for a different checkout, offer, person, or review. `create_order` records the authorized order locally and normally returns before fulfillment completes. It does not collect payment. A `queued` response means Hum durably recorded the order; it does not mean the ISP accepted it or scheduled installation. ## 6. Recover and retrieve Call `get_order` with `checkout_id` to read the latest persisted result. Use it after a successful submission and whenever `create_order` times out, disconnects, returns an uncertain transport result, or loses its response. After an uncertain submission, retrieve first. Do not create a replacement checkout or blindly retry `create_order`. If retrieval says no order was submitted, follow the returned `next_action`; do not infer that a retry is safe. If the result is `submission_unknown`, stop automatic submission and follow Hum's reconciliation or support guidance. ## Fulfillment status language Describe only the evidence Hum returns: | Status | Meaning | | --- | --- | | `queued` | Hum durably recorded the authorized order and queued submission. | | `submitting` | Fulfillment submission is in progress. | | `accepted_by_fulfillment` | Hum recorded acceptance by the fulfillment system. | | `rejected_by_fulfillment` | Hum recorded rejection by the fulfillment system. | | `submission_unknown` | Hum cannot yet prove whether fulfillment accepted the submission; reconciliation is required. | | `not_submitted` | Hum has no recorded fulfillment submission for this checkout; follow the returned next action. | None of these statuses means that the ISP accepted the customer, confirmed serviceability, scheduled installation, or completed installation. Do not translate them into generic checkout, analytics, or activation states. ## Errors and retry behavior Read the structured error, `retryable`, `retry_after_seconds`, field errors, correlation ID, and `next_action` together. Retry only when the result permits it and after the stated delay. For `create_order`, retrieval still comes first after any response that leaves the submission outcome uncertain. An idempotency conflict or duplicate result is not permission to create a new key or checkout. Keep the correlation ID for support without exposing opaque capability values. Ask Hum support to reconcile an unknown outcome when the result directs you to do so. ## Outside this connector Hum does not handle payment through this connector. Cancellation, order modification, Social Security numbers, existing-account credentials, bundles, provider installation tracking, and ISP acceptance are outside this version. Do not promise or simulate those capabilities.