Client and integration runs

`OblidogClient`

Public synchronous client for the Oblidog integration API.

Parameters:

Name	Type	Description	Default
`base_url`	`str`	Root URL of the Oblidog Ledger API.	required
`api_key`	`str`	Integration API key used as a bearer token.	required
`timeout`	`float`	Per-request timeout in seconds.	`10.0`

The client is a context manager; exiting it closes the underlying HTTP connection pool. Its obligations, category_data, and integrations attributes expose the supported SDK operations.

`close()`

Close the underlying synchronous HTTP client.

`IntegrationsClient`

Read authenticated integration context and report runs using its API key.

Callers own run IDs and bounded retries. A conflict must never automatically refresh a revision and replay an old invocation.

`context()`

Return context associated with the authenticated integration API key.

The returned object includes the integration and category selected by the API key. Its current revision is used by :meth:run for optimistic locking.

`run()`

Fetch context and start a run before synchronization work begins.

The context's current revision is used for optimistic locking. Use the returned object as a context manager and finish it explicitly on the successful path.

Example

with client.integrations.run() as run:
    # synchronize using run.context
    run.finish_success(changes_detected=False)

Raises:

Type	Description
`TypeError`	If the context does not contain an integration object with an integer revision.
`OblidogConflictError`	If another worker has changed state first.

`start(*, run_id, expected_revision)`

Start a run using a caller-provided ID and expected revision.

Prefer :meth:run for normal synchronization. This lower-level method is available when the caller explicitly owns scheduling and retries.

Raises:

Type	Description
`OblidogConflictError`	If the revision is stale or a run conflicts.
`OblidogValidationError`	If the request is invalid.

`finish(*, run_id, result, changes_detected=None, error=None)`

Finish a run using the same ID passed to :meth:start.

changes_detected is required by the protocol as a value but can be None when its value is unknown. For failures, supply a sanitized error and avoid secrets or tracebacks.

Raises:

Type	Description
`OblidogConflictError`	If the run cannot be completed in its state.
`OblidogValidationError`	If the completion request is invalid.

`IntegrationRun`

A started integration run that must be finished exactly once.

Obtain instances with :meth:IntegrationsClient.run and normally use them as context managers. An exception before completion reports a sanitized failure and is then propagated to the caller.

`finish_success(*, changes_detected)`

Report successful completion.

Parameters:

Name	Type	Description	Default
`changes_detected`	`bool \| None`	`True` when this run changed Ledger data, `False` for a known no-op, or `None` when unknown.	required

Returns:

Type	Description
`IntegrationPublic`	The finished integration state.

Raises:

Type	Description
`RuntimeError`	If this run was already finished.

`finish_failure(*, code='provider_failed', message='Provider unavailable')`

Report a failure with a sanitized error summary.

Never put credentials, raw provider responses, or tracebacks in message.

`IntegrationContextPublic`

Attributes:

Name	Type	Description
`category`	`IntegrationContextCategoryPublic`
`integration`	`IntegrationContextIntegrationPublic`

`IntegrationContextIntegrationPublic`

Attributes:

Name	Type	Description
`enabled`	`bool`
`id`	`UUID`
`name`	`str`
`revision`	`int`

`IntegrationContextCategoryPublic`

Attributes:

Name	Type	Description
`code`	`str`
`id`	`UUID`
`name`	`str`