Documentation
¶
Index ¶
- Constants
- Variables
- func IsNotFoundError(err error) bool
- func IsProductiveFileURL(raw string) bool
- func LockTaskWorkOrder(tx *gorm.DB, factory *models.Factory, ref TaskRef) error
- func StatusCode(err error) (int, bool)
- func StatusError(statusCode int) error
- func TaskEnvelope(event string, document map[string]any, organizationID string) map[string]any
- func TaskHasWorkOrder(tx *gorm.DB, factory *models.Factory, ref TaskRef) (bool, error)
- func TaskIDFromEventData(eventData any) (string, bool)
- func TaskIDFromURL(rawURL string) (string, bool)
- func TaskURL(organizationID, taskID string) string
- func TaskURLFragment(taskID string) string
- type Attachment
- type Client
- func (c *Client) CreateWebhook(webhookURL string, eventID int, eventName string) (*Webhook, error)
- func (c *Client) DeleteWebhook(id string) error
- func (c *Client) GetProject(id string) (*Project, error)
- func (c *Client) GetTask(id string) (*Task, error)
- func (c *Client) ListNewestOpenTaskDocuments(projectID string, limit int, regularOnly bool, taskListIDs []string) ([]map[string]any, error)
- func (c *Client) ListProjects() ([]Project, error)
- func (c *Client) ListTaskAttachments(taskID string) ([]Attachment, error)
- func (c *Client) ListTaskLists(projectID string) ([]TaskList, error)
- func (c *Client) ListTasks(projectID, query string, limit int, regularOnly bool, taskListIDs []string) ([]Task, error)
- func (c *Client) TaskFiles(ctx context.Context, taskID, description string) ([]TaskFile, error)
- func (c *Client) ValidateCredentials() error
- func (c *Client) ValidateWebhookPermission() error
- type NodeMetadata
- type OnTask
- func (t *OnTask) Cleanup(ctx core.TriggerContext) error
- func (t *OnTask) Color() string
- func (t *OnTask) Configuration() []configuration.Field
- func (t *OnTask) Description() string
- func (t *OnTask) Documentation() string
- func (t *OnTask) ExampleData() map[string]any
- func (t *OnTask) HandleHook(ctx core.TriggerHookContext) (map[string]any, error)
- func (t *OnTask) HandleWebhook(ctx core.WebhookRequestContext) (int, *core.WebhookResponseBody, error)
- func (t *OnTask) Hooks() []core.Hook
- func (t *OnTask) Icon() string
- func (t *OnTask) Label() string
- func (t *OnTask) Name() string
- func (t *OnTask) Setup(ctx core.TriggerContext) error
- type OnTaskConfiguration
- type Productive
- func (p *Productive) Actions() []core.Action
- func (p *Productive) Cleanup(ctx core.IntegrationCleanupContext) error
- func (p *Productive) Configuration() []configuration.Field
- func (p *Productive) Description() string
- func (p *Productive) HandleHook(ctx core.IntegrationHookContext) error
- func (p *Productive) HandleRequest(ctx core.HTTPRequestContext)
- func (p *Productive) Hooks() []core.Hook
- func (p *Productive) Icon() string
- func (p *Productive) Instructions() string
- func (p *Productive) Label() string
- func (p *Productive) ListResources(resourceType string, ctx core.ListResourcesContext) ([]core.IntegrationResource, error)
- func (p *Productive) Name() string
- func (p *Productive) Sync(ctx core.SyncContext) error
- func (p *Productive) Triggers() []core.Trigger
- type ProductiveWebhookHandler
- func (h *ProductiveWebhookHandler) Cleanup(ctx core.WebhookHandlerContext) error
- func (h *ProductiveWebhookHandler) CompareConfig(a, b any) (bool, error)
- func (h *ProductiveWebhookHandler) Merge(current, requested any) (any, bool, error)
- func (h *ProductiveWebhookHandler) Setup(ctx core.WebhookHandlerContext) (any, error)
- type Project
- type Task
- type TaskFile
- type TaskList
- type TaskListMove
- type TaskRef
- type Webhook
- type WebhookConfiguration
- type WebhookMetadata
Constants ¶
const ( // BaseURL is Productive.io's API v2 base URL, used unless the "region" // configuration field overrides it. BaseURL = "https://api.productive.io/api/v2" // AuthTokenHeader carries the Productive.io API token on every request. AuthTokenHeader = "X-Auth-Token" // OrganizationIDHeader scopes every request to one Productive.io // organization. Productive.io issues tokens per person, not per // organization, so this header is required on every call. OrganizationIDHeader = "X-Organization-Id" // TaskPayloadType is the payload type the onTask trigger emits. TaskPayloadType = "productive.task" // ResourceTypeProject is the resource type projects are listed and picked // as, both for the onTask trigger's project field and ListResources. ResourceTypeProject = "project" // ResourceTypeTaskList is a task list inside one project. ListResources // requires a "project" parameter with that project's id. ResourceTypeTaskList = "task_list" // TaskCreatedEvent and TaskUpdatedEvent name the change a task event // carries, in the "meta" object of the emitted envelope. TaskCreatedEvent = "task.created" TaskUpdatedEvent = "task.updated" // ActionCreated and ActionUpdated are the values of the onTask trigger's // "actions" field. ActionCreated = "created" ActionUpdated = "updated" // WebhookTypeStandard is Productive.io type_id for a normal webhook // (not Zapier). WebhookTypeStandard = 1 // EventNewTask and EventUpdatedTask are Productive.io event_id values // for task created and task updated. EventNewTask = 1 EventUpdatedTask = 24 // TaskTypeRegular is a normal Productive.io task. TaskTypeMilestone is // a key task. TaskTypeRegular = 1 TaskTypeMilestone = 3 // EventHeader is a custom header SuperPlane asks Productive.io to send. // Productive.io does not send it on real deliveries, so the signature // token is what tells a created task from an updated task. EventHeader = "X-Productive-Event" // SignatureHeader carries Productive.io's HMAC of timestamp + "." + body. SignatureHeader = "Productive-Signature" )
Variables ¶
var ErrMissingWritePermission error = missingWritePermissionError{}
ErrMissingWritePermission reports that the API token can authenticate but cannot create webhooks. Error returns the message shown to the user.
var ErrWebhooksLimitExceeded = errors.New("productive.io plan does not include webhooks")
ErrWebhooksLimitExceeded reports that Productive.io rejected a webhook registration because the organization's plan does not include webhooks.
Functions ¶
func IsNotFoundError ¶
func IsProductiveFileURL ¶
IsProductiveFileURL reports whether raw points at a Productive.io file download. API resources under /api/v2/attachments are not file downloads.
func LockTaskWorkOrder ¶
LockTaskWorkOrder serializes work-order creation for one Productive.io task in this factory. The lock is held until the caller commits tx.
func StatusCode ¶
func StatusError ¶
func TaskEnvelope ¶
TaskEnvelope wraps a task resource the way every consumer of this trigger reads it: the JSON:API resource under "data", the change that produced it under "meta", and the Productive.io task page under "url" when the organization id is known. Seeded tasks use the same shape, so nothing downstream can tell a seeded task from a polled one.
func TaskHasWorkOrder ¶
TaskHasWorkOrder reports whether this factory already has a work order for this Productive.io task. Matching covers every work-order state, both by origin URL and by an origin-less work order whose source run is this task (webhook bodies used to omit the page URL).
func TaskIDFromEventData ¶
TaskIDFromEventData reads the Productive.io task id from a canvas root event. The envelope looks like:
{ "type": "productive.task", "data": { "data": { "id": "20305431" } } }
func TaskIDFromURL ¶
TaskIDFromURL reads the Productive.io task id from a task page URL.
func TaskURL ¶
TaskURL is the Productive.io page for one task. Work orders store this as origin so a later update of the same task does not create another one.
func TaskURLFragment ¶
TaskURLFragment is the origin-URL substring that identifies a Productive.io task. Callers use it for a coarse lookup, then confirm with TaskIDFromURL so `/tasks/9` cannot match `/tasks/91`.
Types ¶
type Attachment ¶
Attachment is a file linked to a Productive.io task. The webhook payload does not include these records. They come from GET /attachments.
type Client ¶
type Client struct {
APIToken string
OrganizationID string
BaseURL string
// contains filtered or unexported fields
}
Client talks to Productive.io's JSON:API v2 API using an API token and an organization id, both sent as headers on every request.
func NewClient ¶
func NewClient(httpCtx core.HTTPContext, ctx core.IntegrationContext) (*Client, error)
func (*Client) CreateWebhook ¶
CreateWebhook registers an organization webhook that POSTs eventID deliveries to webhookURL. eventName is sent back on each delivery as EventHeader. Productive.io answers 403 webhooks_limit_exceeded (surfaced as ErrWebhooksLimitExceeded) on plans that do not include webhooks.
func (*Client) DeleteWebhook ¶
DeleteWebhook removes a webhook by its Productive.io resource id.
func (*Client) GetProject ¶
GetProject fetches a single project by id, for resolving the project a trigger was configured with into the name shown on its canvas card.
func (*Client) ListNewestOpenTaskDocuments ¶
func (c *Client) ListNewestOpenTaskDocuments(projectID string, limit int, regularOnly bool, taskListIDs []string) ([]map[string]any, error)
ListNewestOpenTaskDocuments returns the untrimmed JSON:API resource of each open task in the project, newest first. Seeding an intake replays these through the graph the trigger feeds, and that graph reads attributes Task does not keep.
func (*Client) ListProjects ¶
ListProjects returns every project of the organization. Productive.io paginates responses, so pages are walked until a short page ends them.
func (*Client) ListTaskAttachments ¶
func (c *Client) ListTaskAttachments(taskID string) ([]Attachment, error)
ListTaskAttachments returns files linked to one task. Deleted rows are omitted.
func (*Client) ListTaskLists ¶
ListTaskLists returns the active task lists of one project. Productive.io paginates responses, so pages are walked until a short page ends them.
func (*Client) ListTasks ¶
func (c *Client) ListTasks(projectID, query string, limit int, regularOnly bool, taskListIDs []string) ([]Task, error)
ListTasks returns open tasks from one project, optionally filtered by text. When regularOnly is set, key tasks (milestones) are omitted. A non-empty taskListIDs keeps tasks that belong to those task lists.
func (*Client) TaskFiles ¶
TaskFiles downloads the files attached to a task, plus Productive.io file URLs already written in description. The API token is added only on the download request. It is not returned.
func (*Client) ValidateCredentials ¶
ValidateCredentials confirms the token and organization id are accepted by Productive.io. Organization memberships is the cheapest authenticated endpoint that also proves the organization id header is correct: a token valid for a different organization is rejected before any data is read.
func (*Client) ValidateWebhookPermission ¶
ValidateWebhookPermission confirms the token can create webhooks.
The probe posts a webhook with empty attributes. Productive rejects that body when the token can write, and rejects the request earlier when it cannot. A webhook that is created anyway is deleted before this returns.
type NodeMetadata ¶
type NodeMetadata struct {
Project *Project `json:"project,omitempty" mapstructure:"project,omitempty"`
}
NodeMetadata is stored on productive.onTask nodes, so canvas cards can show the project without re-querying Productive.io.
type OnTask ¶
type OnTask struct{}
func (*OnTask) Configuration ¶
func (t *OnTask) Configuration() []configuration.Field
func (*OnTask) Description ¶
func (*OnTask) Documentation ¶
func (*OnTask) ExampleData ¶
func (*OnTask) HandleHook ¶
func (*OnTask) HandleWebhook ¶
func (t *OnTask) HandleWebhook(ctx core.WebhookRequestContext) (int, *core.WebhookResponseBody, error)
HandleWebhook emits the productive.task envelope for a task.created or task.updated delivery, filtered to the actions this node was configured to listen for.
type OnTaskConfiguration ¶
type Productive ¶
type Productive struct{}
func (*Productive) Actions ¶
func (p *Productive) Actions() []core.Action
func (*Productive) Cleanup ¶
func (p *Productive) Cleanup(ctx core.IntegrationCleanupContext) error
func (*Productive) Configuration ¶
func (p *Productive) Configuration() []configuration.Field
func (*Productive) Description ¶
func (p *Productive) Description() string
func (*Productive) HandleHook ¶
func (p *Productive) HandleHook(ctx core.IntegrationHookContext) error
func (*Productive) HandleRequest ¶
func (p *Productive) HandleRequest(ctx core.HTTPRequestContext)
func (*Productive) Hooks ¶
func (p *Productive) Hooks() []core.Hook
func (*Productive) Icon ¶
func (p *Productive) Icon() string
func (*Productive) Instructions ¶
func (p *Productive) Instructions() string
func (*Productive) Label ¶
func (p *Productive) Label() string
func (*Productive) ListResources ¶
func (p *Productive) ListResources(resourceType string, ctx core.ListResourcesContext) ([]core.IntegrationResource, error)
func (*Productive) Name ¶
func (p *Productive) Name() string
func (*Productive) Sync ¶
func (p *Productive) Sync(ctx core.SyncContext) error
func (*Productive) Triggers ¶
func (p *Productive) Triggers() []core.Trigger
type ProductiveWebhookHandler ¶
type ProductiveWebhookHandler struct{}
ProductiveWebhookHandler creates and tears down the Productive.io webhooks the onTask trigger subscribes to.
func (*ProductiveWebhookHandler) Cleanup ¶
func (h *ProductiveWebhookHandler) Cleanup(ctx core.WebhookHandlerContext) error
func (*ProductiveWebhookHandler) CompareConfig ¶
func (h *ProductiveWebhookHandler) CompareConfig(a, b any) (bool, error)
func (*ProductiveWebhookHandler) Merge ¶
func (h *ProductiveWebhookHandler) Merge(current, requested any) (any, bool, error)
func (*ProductiveWebhookHandler) Setup ¶
func (h *ProductiveWebhookHandler) Setup(ctx core.WebhookHandlerContext) (any, error)
type Project ¶
Project is a Productive.io project, used by the onTask trigger's project picker and to scope a webhook to one project.
type Task ¶
type Task struct {
ID string
Number string
Title string
Description string
ProjectID string
TaskListID string
Closed bool
TypeID int
}
Task is a Productive.io task that can seed a factory intake.
type TaskFile ¶
TaskFile is a downloaded Productive.io file ready to store on a work order. ReplaceURLs are the exact description strings that should become the stored file reference. An empty list means the file is appended.
type TaskListMove ¶
TaskListMove is a Productive.io task changing task lists. From and To are task list ids. An empty From means the task had no list.
type TaskRef ¶
TaskRef identifies one Productive.io task in one Productive organization. Task ids are unique inside an organization, not across organizations.
func TaskRefFromEventData ¶
TaskRefFromEventData reads the Productive.io task id and organization from a canvas root event. The organization comes from the task page URL. Older events omit that URL, so OrganizationID can be empty.
func TaskRefFromURL ¶
TaskRefFromURL reads the Productive.io organization and task id from a task page URL.
type Webhook ¶
Webhook is a Productive.io webhook subscription. Productive.io webhooks are organization-wide and fire for one event_id each.
type WebhookConfiguration ¶
type WebhookConfiguration struct {
ProjectID string `json:"projectId" mapstructure:"projectId"`
}
WebhookConfiguration scopes a SuperPlane webhook to one Productive.io project. Remote webhooks are organization-wide; the project id is used to share one SuperPlane webhook among nodes and to filter deliveries.
type WebhookMetadata ¶
type WebhookMetadata struct {
IDs []string `json:"ids" mapstructure:"ids"`
// ID is the single remote id the invented API stored. Cleanup still
// deletes it so an old record does not leak a Productive.io webhook.
ID string `json:"id,omitempty" mapstructure:"id,omitempty"`
}
WebhookMetadata is stored on the webhook record after remote webhooks are created, so Cleanup can delete each Productive.io webhook again.