Codat.Platform.PushOperations (codat v1.0.0)

Track asynchronous write (push) operations.

All Codat write operations (create, update, delete) are asynchronous. The API immediately returns a push operation in Pending status. Use this module to poll for completion, or subscribe to the appropriate webhook event (e.g., invoices.write.successful).

Push Operation Statuses

Status	Description
`Pending`	Operation queued, not yet processed by the integration.
`Processing`	Operation is being submitted to the accounting platform.
`Success`	Operation completed successfully. Data is in the platform.
`Failed`	Operation failed. Check `errorMessage` and `validation` fields.
`TimedOut`	Operation exceeded the configured `timeoutInMinutes`.

Example

# Create an invoice — returns a push operation immediately
{:ok, push_op} = Codat.Accounting.Invoices.create(client, company_id, conn_id, body)
key = push_op["pushOperationKey"]

# Poll until complete (or subscribe to webhooks instead)
{:ok, op} = Codat.Platform.PushOperations.poll_until_done(client, company_id, key)
op["status"]  # => "Success"

Summary

Functions

get(client_or_company_id, company_or_key, key_or_opts \\ [])

Returns a single push operation by its key.

list(client_or_company_id, company_id_or_opts \\ [], opts \\ [])

Returns a paginated list of push operations for a company.

poll_until_done(client_or_company_id, company_or_push_key, push_key_or_opts \\ [], opts \\ [])

Polls a push operation until it reaches a terminal status (Success, Failed, TimedOut) or the polling timeout is exceeded.

Functions

get(client_or_company_id, company_or_key, key_or_opts \\ [])

@spec get(Codat.Client.t() | String.t(), String.t(), String.t() | keyword()) ::
  {:ok, map()} | {:error, Codat.Error.t()}

Returns a single push operation by its key.

Example

{:ok, op} = Codat.Platform.PushOperations.get(client, "company-id", "push-op-key")
op["status"]           # => "Success"
op["dataType"]         # => "invoices"
op["completedOnUtc"]   # => "2024-01-15T10:30:00Z"

list(client_or_company_id, company_id_or_opts \\ [], opts \\ [])

@spec list(Codat.Client.t() | String.t(), String.t() | keyword(), keyword()) ::
  {:ok, Codat.Pagination.t()} | {:error, Codat.Error.t()}

Returns a paginated list of push operations for a company.

Options

:page, :page_size — pagination
:query — filter, e.g. "status=Failed&&dataType=invoices"

Example

{:ok, page} = Codat.Platform.PushOperations.list(client, "company-id")
{:ok, page} = Codat.Platform.PushOperations.list("company-id", query: "status=Failed")

poll_until_done(client_or_company_id, company_or_push_key, push_key_or_opts \\ [], opts \\ [])

@spec poll_until_done(
  Codat.Client.t() | String.t(),
  String.t(),
  String.t() | keyword(),
  keyword()
) :: {:ok, map()} | {:error, Codat.Error.t()}

Polls a push operation until it reaches a terminal status (Success, Failed, TimedOut) or the polling timeout is exceeded.

Options

:poll_interval — ms between polls (default: 2000ms)
:timeout — max total wait time in ms (default: 120000ms)

Returns

{:ok, push_op} with status: "Success" on success
{:ok, push_op} with status: "Failed" if the operation failed in the integration
{:error, %Codat.Error{type: :timeout}} if polling timed out
{:error, %Codat.Error{}} on HTTP error

Example

{:ok, op} = Codat.Platform.PushOperations.poll_until_done(
  client, "company-id", "push-key",
  poll_interval: 1_000,
  timeout: 60_000
)

case op["status"] do
  "Success" -> IO.puts("Created! ID: " <> op["data"]["id"])
  "Failed"  -> IO.puts("Failed: " <> op["errorMessage"])
end