@spec create(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.PostApiV1SlackChannelBindings.Input.t()
) ::
  {:ok, ArchAstro.Types.SlackChannelBinding.t()}
  | {:error, ArchAstro.Error.reason()}

Create or update a Slack channel binding

Creates a new binding between a Slack channel and a team, or updates the existing binding if one already exists for the given channel. The caller also supplies a list of agents to attach to the binding and enroll as members of the destination team.

The caller must have team-manage rights on the destination team (and on the currently bound team if the channel is being re-pointed). Returns 403 if permission is insufficient. All write steps are idempotent, so retrying after a partial failure is safe.

On success the REST endpoint returns 201 Created. The script binding (slack.channel_bindings.upsert) returns the full binding object including the attached agents.

The created or updated Slack channel binding, including the full list of currently attached agents.

@spec delete(ArchAstro.Client.t(), String.t()) ::
  {:ok,
   ArchAstro.Types.Operations.DeleteApiV1SlackChannelBindingsChannel.Response.t()}
  | {:error, ArchAstro.Error.reason()}

Delete a Slack channel binding

Removes the binding between a Slack channel and its associated team. The channel is identified by its Slack channel ID together with the slack_team_id that scopes it to a specific Slack workspace. Removing the binding does not delete the bound team or any conversation threads scoped to it; decommission those resources separately if required.

The caller must have team-manage rights on the team the channel is currently bound to. Returning 403 indicates insufficient permission; returning 404 indicates the binding does not exist or is not visible to the caller.

The REST endpoint returns 204 No Content on success. The script binding (slack.channel_bindings.delete) returns a confirmation object so script callers can verify success without an additional fetch. Both paths are idempotent — retrying after a partial failure is safe.

Successful response

@spec deposit_thread(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.PostApiV1SlackChannelBindingsChannelDepositThread.Input.t()
) ::
  {:ok, ArchAstro.Types.SlackChannelBinding.t()}
  | {:error, ArchAstro.Error.reason()}

Point a Slack channel's deposit pipe at a staging thread, or turn it off

Sets the binding's deposit target — the internal staging thread the deposit pipe copies this channel's mirror content into. Pass a null thread_id to turn the pipe off.

The target is validated server-side: it must exist, belong to the binding's app and org, and never be a Slack mirror thread. Customer bindings (bound team_id) additionally require a team-owned private thread with no participant list, so the staging read ACL stays governed by the channel-membership projection. Re-pointing or clearing an existing target purges the old thread's deposit entries.

The binding with the updated deposit config.

@spec get(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.GetApiV1SlackChannelBindingsChannel.Params.t()
) ::
  {:ok, ArchAstro.Types.SlackChannelBinding.t()}
  | {:error, ArchAstro.Error.reason()}

Retrieve a Slack channel binding

Returns the Slack channel binding identified by a Slack channel ID and workspace team ID pair. Use this endpoint to look up the team and agents currently bound to a specific Slack channel.

The channel path parameter is the Slack channel ID; slack_team_id identifies the Slack workspace the channel belongs to, disambiguating channels with the same ID across workspaces. Both parameters are required. Returns 404 if no binding exists for the given pair or the associated Slack integration is not visible to the caller.

The Slack channel binding for the given channel and workspace.

@spec list(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.GetApiV1SlackChannelBindings.Params.t()
) ::
  {:ok, ArchAstro.Types.SlackChannelBindingListResponse.t()}
  | {:error, ArchAstro.Error.reason()}

List Slack channel bindings

Returns a page of Slack channel bindings visible to the authenticated user. Results can be filtered by integration, team, agent, or organization. Omit all filter params to retrieve every binding the caller can see.

Pagination is page-based. Pass page and per_page to navigate large result sets. page must be a positive integer; per_page must be between 1 and 100. Invalid values return 400.

Paginated list of Slack channel bindings visible to the caller.

@spec provision(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.PostApiV1SlackChannelBindingsProvision.Input.t()
) ::
  {:ok, ArchAstro.Types.SlackChannelBinding.t()}
  | {:error, ArchAstro.Error.reason()}

Start adding a customer over Slack Connect

Opens a Slack Connect channel with a new customer — creating one and sending the invite, or adopting a shared channel you already have — and records who is adding whom so the addition can finish once the customer accepts.

The returned binding is pending: nothing mirrors, and no per-customer Team, agent, or solution instance exists yet. Acceptance is asynchronous and may never come. When it does, the addition completes in the background under the identity of the admin who called this endpoint, re-checked live at that moment. A caller who has since lost their admin role does not get a substitute — the addition is refused and a human re-adds the customer.

The caller must be an admin of the Slack integration's own organization. This is the same authority the completion demands, checked here so a customer is never invited into a channel whose addition can never finish.

Deliberately not exposed as a script binding: this sends mail to a person outside the org, so it stays a vendor-admin HTTP surface.

The pending binding for the customer's channel. disclosure_state is pending until the customer accepts, and scope_key is null until the addition finishes.