Testing & observability

Testing tools

Every SDK includes a fake transport for testing your code that uses the SDK without a network or an API Key. Nothing is actually sent; requests are recorded, and you can inject the responses or errors you want.

import io.github.icommapi.bizgo.testing.*;

FakeTransport fake = new FakeTransport();
Bizgo client = fake.client(); // fake key, rate limit off, no network

client.send().sms("01000000000", "01000000000", "hello"); // default: A000 + fake msgKey per recipient
RecordedRequest request = fake.lastRequest();
assertEquals("sendOmni", request.getOperationId());

fake.on("sendOmni")
        .thenFail(ErrorLayer.SERVICE, 429, "A020")      // next call: rate limited
        .thenSendResult("A000", "A306");                // then: second recipient rejected

// signed webhook request for tests (same signing as production)
WebhookSigner.SignedWebhook hook = WebhookSigner.sign("test-webhook-secret", "{\"msgKey\":\"K001\"}");
ReportWebhookPayload report = new WebhookReceiver("test-webhook-secret").report(hook.headers(), hook.body());

• Default responses: Without a stub, calls succeed. Sends and reservation creation return A000 and a fake msgKey per recipient; other APIs return an empty result.
• Injecting responses: You can set success results, service or gateway errors, network errors, and timeouts. They are used in order, and the last one repeats.
• Recording: Each request records the operation, method, path, query, and JSON body. Header values (including the API Key) are never recorded.

Observability (hooks)

A start and an end hook run for every API call: once per call including retries (once per attempt in C#). Use them for metrics and logs.

Hooks receive only the operationId, resource.method (such as send.omni), the HTTP method, the path template (/api/comm/v1/report/inquiry/{msgKey}), the status code, the error layer and code, the attempt count, and the duration. Bodies, queries, header values, actual path values, phone numbers, and API Keys are never passed. The SDK ignores exceptions thrown in a hook, so they never affect the send result.

Bizgo client = Bizgo.builder()
        .hook(new RequestHook() {
            @Override
            public void onRequestEnd(RequestEvent e) {
                metrics.record(e.getOperationId(), e.getStatus(), e.getErrorCode(), e.getAttempts(), e.getDuration());
            }
        })
        .build();

OpenTelemetry

Every SDK can create one CLIENT span per call. The span name is bizgo <resource>.<method> (such as bizgo send.omni), and the attributes are http.request.method, url.template, http.response.status_code, bizgo.operation_id, bizgo.code, bizgo.layer, bizgo.retry_count, and error.type on failure. No trace headers are sent to Bizgo.

OpenTelemetry support is optional, so add the package below only when you use it. The SDK core gains no dependencies.

// implementation 'io.github.icomm-api:bizgo-sdk-comm-java-opentelemetry:1.2.0'
Bizgo client = Bizgo.builder().hook(BizgoTracing.create(GlobalOpenTelemetry.get())).build();

The C# netstandard2.0 build (.NET Framework and so on) does not create spans, to avoid adding dependencies. Connect it through hooks instead.