Integration methods: call, connect, pause
The Integration Verbs call, connect, pause as typed SDK methods, with inputs, result, refusals and an example.
Reference for Integration, one group of Integration methods.
Integration.call
Call sends one request to an upstream through an Integration, with its token filled in server-side, for endpoints no Mapping covers. Verb page.
interface IntegrationVerbs {
call(input: IntegrationCallInput, options?: SB.CallOptions): SB.Call<IntegrationCallOutput>
}Emits Integration.called.
Inputs
| Input | Type | Required | Description |
|---|---|---|---|
integration | Integration | required | The Integration to call through. |
method | string | required | The HTTP method; GET runs at once. |
path | string | required | The upstream path, inside the Integration’s grants. |
body | json | The request body. |
Returns
| Output | Type | Required | Description |
|---|---|---|---|
status | integer | required | The upstream’s status code. |
body | json | The upstream’s response body. | |
integration | Integration | required | The Integration the request went through. |
Refuses when
| Check | Error | Fix | Then call |
|---|---|---|---|
| The key is valid, but its scopes do not allow this operation. | forbidden | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |
| A path outside the Integration’s grants before it leaves the platform | refused | Clear what the check names, then call it again. | None. |
Example
import { $ } from 'startup-builder'
const { status, body, integration } = await $.Integration.call({ integration: 'integration_alVwjQcmRy', method: 'GET', path: '/' })Integration.connect
Connect asks an account holder to approve an outside account for one System and records the grants they approve. Verb page.
interface IntegrationVerbs {
connect(input: IntegrationConnectInput, options?: SB.CallOptions): SB.Call<IntegrationConnectOutput>
}Emits Integration.connected.
Inputs
| Input | Type | Required | Description |
|---|---|---|---|
system | System | required | The System the Integration serves. |
scope | string | required | One of studio, startup or customer; a person’s own account is startup, narrowed to them. |
grants | string[] | required | The access requested, shown to the account holder before they approve. |
venue | string | The id of the ad, social or app-store venue the account is on. | |
for | Party | The account holder, when an Agent asks on their behalf. |
Returns
| Output | Type | Required | Description |
|---|---|---|---|
integration | Integration | required | The Integration, connecting until approved. |
connectUrl | url | required | The approval page on the upstream’s own site; it expires in one hour. |
Refuses when
| Check | Error | Fix | Then call |
|---|---|---|---|
| The key is valid, but its scopes do not allow this operation. | forbidden | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |
Example
import { $ } from 'startup-builder'
const { integration, connectUrl } = await $.Integration.connect({ system: 'system_uGWze2jvrp', scope: 'studio', grants: ['Example grants'] })Integration.pause
Pause stops every call through an Integration at once and keeps its token and cursor. Verb page.
interface IntegrationVerbs {
pause(input: IntegrationPauseInput, options?: SB.CallOptions): SB.Call<Integration>
}Emits Integration.paused.
Inputs
| Input | Type | Required | Description |
|---|---|---|---|
integration | Integration | required | The Integration to pause. |
reason | text | Why, shown to every Worker whose Action waits on it. |
Returns
| Output | Type | Required | Description |
|---|---|---|---|
integration | Integration | required | The Integration, paused. |
Refuses when
| Check | Error | Fix | Then call |
|---|---|---|---|
| The key is valid, but its scopes do not allow this operation. | forbidden | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |
Example
import { $ } from 'startup-builder'
const integration = await $.Integration.pause({ integration: 'integration_alVwjQcmRy' })