atomist.api — com.atomist/api-cljs 0.5.90

actionable-message cljs

(actionable-message o slack & [opts])

attachment style messages with actions - try to switch to block messages params o - incoming command request or event payload slack - slack Message data where all actions may refer to other CommandHandlers

add-actions cljs

(add-actions o actions)

actions must be an [] of {:keys [id command parameters]} (parameter optional)

• we are not adding the :automation map to the action (assumes all actions route to this skill)
• TODO we need to warn if a request does not contain an automation field (which can happen when things come in from events).
• this adds the special messageId parameter to each action

add-destination cljs

(add-destination o
                 {:keys [id name] :as chat-team}
                 {:keys [id name] :as channel})

add slack team channel to existing desintations

add-gitub-installation-token cljs

(add-gitub-installation-token handler k)

add-message-id cljs

(add-message-id ch-request)

ensure message id

• whether request has an id or a messageId parameter
• use guid if not

add-post-mode cljs

(add-post-mode request mode)

add-resource-providers cljs

(add-resource-providers handler)

process any resource providers included in the configuration

• use typeName to run a graphql query
• add graphql response to the request at [:atomist/resource-providers (keyword resource-provider-name)] the data added is an array of ResourceProvider maps

add-skill-config cljs

(add-skill-config handler & ks)

request middleware that looks for configuration added for a skill with dispatchStyle equal to multiple

if the request has a configuration then named configuration values are merged into the request using a keywordized map

add-skill-config-by-configuration-parameter cljs

(add-skill-config-by-configuration-parameter handler parameter-name & ks)

request middleware that can be used by command handlers to lookup a particular skill configuration and reflect it into the request.

params parameter-name is keyword for the required configuration name ks the names of config parameters that should be reflected into the skill

add-slack-source-to-event cljs

(add-slack-source-to-event handler & {:keys [channel team-id]})

api middleware team-id is optional - if not provided, we pull it in from the graph channel is mandatory and serves as the default destination

apply-repo-filter cljs

(apply-repo-filter handler & ks)

check whether request ref is in scope requires that a scope parameter has been added to the request and has includes/excludes

block-message cljs

(block-message o blocks)

params blocks - array of Slack blocks (not a map!) TODO - validate that all blocks with actions have valid action attached

by-50 cljs

(by-50 coll)

channel cljs

(channel o c)

set first destination channel name params o - command request or incoming event payload c - string name of message channel

check-required-parameters cljs

(check-required-parameters handler & parameters)

request middleware used during command handler processing to check that required parameters are present

• if the request is a command handler request and has missing parameters then the bot will go back to the user to get more data
• if the required parameters are all present then the pipeline will continue with the parameter values keywordized and merged into the request

check-run-transaction cljs

(check-run-transaction {:keys [sha repo-id]} check-response)

params ref GitHub response after creating CheckRun

check-tx cljs

(check-tx cname title status & [conclusion])

Generate a transaction for a skill configuration check

checks-action->enum cljs

(checks-action->enum check-type action)

checks-conclusion->enum cljs

(checks-conclusion->enum check-type conclusion)

checks-status->enum cljs

(checks-status->enum check-type status)

clone-ref cljs

(clone-ref handler)

clone a ref and augment request with a :atomist/project at key :project

command-handlers cljs

(command-handlers dispatch-map)

create a top-level handler function for a dispatch map of command names to command handlers Set up the middleware as if request needs a github token

compose-middleware cljs

(compose-middleware & args)

config-iterator cljs

(config-iterator join-handler forked-handler)

continue cljs

(continue o params)

continue this request with some additional parameter specs (all added parameters must be required)

create-ref-from-event cljs

(create-ref-from-event handler
                       &
                       {:keys [stop-if-missing] :or {stop-if-missing true}})

create-ref-from-first-linked-repo cljs

(create-ref-from-first-linked-repo handler)

request middleware use a requests's :linked-repos to construct a git ref with {:keys [repo owner branch]}

• the repo name is a parameter expression which can use parameter values
• currently always using master branch (should this be a middleware parameter?)

creds-kill cljs

(creds-kill data)

delete-message cljs

(delete-message o)

dispatch cljs

(dispatch dispatch-map)

create a request handler using a map where the keys are command names or event subscription operations and the values are request handlers

edit-inside-PR cljs

(edit-inside-PR handler configuration)

mostly run editor inside a PR but also allow for running with a commit on master params configuration - :editor/configuration

event->request cljs

(event->request request)

adds :operation :data :api_version :team :correlation_id to the non-command requests

extract-cli-parameters cljs

(extract-cli-parameters handler options)

request middleware used during command handler processing to parse the raw bot message into cli parameters. The parameters are merged into the request keywordized.

middleware-params options - must contain a clojure.tools.cli option parser definition

extract-github-token cljs

(extract-github-token handler)

request middleware will extract a github token by trying a few strategies

• first check whether any request middleware has already found a github provider with a credential secret This is used when we have a shared authorization for the ResourceProvider

• second, check whether any request middleware has stored a ref with an owner org. If so, check whether this org has a GitHub Installation and then fetch an Installation token for this Org.

If we find a token store it in the request under the :token key. If we don't find a token, continue anyway. It's possible a good idea to supply an option to stop processing if no token is found.

extract-github-user-token cljs

(extract-github-user-token handler)

request middleware used during command handler processing to extract a github user token from a request

• if this middleware finds that the chat user is linked to an authorized ScmProvider then the token will be added to the request
• if the current user is not authorized then the bot will ask the user authorize and then stop the pipeline with status success.

extract-github-user-token-by-github-login cljs

(extract-github-user-token-by-github-login handler)

request middleware used during command handler processing to extract a github user token from a request

• if this middleware finds that the chat user is linked to an authorized ScmProvider then the token will be added to the request
• if the current user is not authorized then the bot will ask the user authorize and then stop the pipeline with status success.

extract-linked-repos cljs

(extract-linked-repos handler)

request middleware used during command handler processing to extract the set of linked repos for this channel

• processor will stop if there are no linked channels so this should be inserted in the pipeline only when >0 linked channels should be found. It will output a message if there are zero linked channels

extract-parameters cljs

(extract-parameters handler)

merge all command handler parameters so they can be looked up associatively

finished cljs

(finished & {:keys [message success]})

convenient function to generate a request handler to put at the end of a chain of middleware

options :message - log a finished message into the User log :success - set the reason string in a success status message

from cljs

(from handler f & {:keys [key]})

from-channel cljs

(from-channel handler ->channel & {:keys [key] :or {key :results}})

request middleware that pauses to run an async function ->channel and then continues with the functions result merged into request

middleware params ->channel function (request) => channel where the channel result is needed by downstream processors key - the key to use when merging the async result into the request map

get-parameter-value cljs

(get-parameter-value o parameter-name)

search command request for parameter params o - command request parameter-name - string name returns nil if there's no parameter

get-secret-value cljs

(get-secret-value o secret-uri)

@deprecated

graphql-resource-providers cljs

ingest cljs

(ingest o x channel)

@deprecated ingest a new custom event params o - incoming event or command request x - custom event channel - name of custom event channel

log-event cljs

(log-event handler)

make-request cljs

(make-request data sendreponse handler)

This is probably the only function that should be called in a cljs skill handler. It kicks off the request handler.

• start with the incoming PubSubMessage.data, keywordize it, and use it as the request map
• wrap the whole request processor in a Promise to satisfy the gcf Node.js runtime
• create a done channel in the request so that request processing pipeline can finish early
• wrap the whole pipeline in a try catch block
• add a callback sendreponse function to the request map to handle writing events to the response topic
• success/fail status are normally handled in the pipeline, but exception cases handled here will result in fail status

mapped-parameter-value cljs

(mapped-parameter-value o parameter-name)

@deprecated search command request for mapped parameter params o - command request parameter-name - string name returns nil if there's no parameter

merge-into-request cljs

(merge-into-request handler m)

mw-dispatch cljs

(mw-dispatch handler dispatch-map)

parameter-expression cljs

(parameter-expression ch-request expression)

post-mode cljs

(post-mode handler mode)

repo->slug cljs

(repo->slug {repo-name :name {org :owner} :org})

repo-iterator cljs

(repo-iterator join-handler forked-handler)

(repo-iterator join-handler ref-filter forked-handler)

run a handler (forked-handler) over all of our current repos

forked-handler should return a channel that will emit one value when the forked handler is finished

• start with a channel that emits all the visible repo-refs in this team
• map the forked-handler over these refs which means we will end up with a coll of channels
• merge these channels and then reduce them into an array - this array will contain the results of all of the forked handlers

when the final channel for the reduced results closes, we can run the join handler to continue the outer pipeline

run-command cljs

(run-command handler & {:keys [cmd ->args on-success on-failure]})

send-fingerprints cljs

(send-fingerprints handler)

request middleware that will look for fingerprints in the request and send them to Atomist

set-message-id cljs

(set-message-id handler)

request middleware used during command handler processing to extract messageIds or create new random ones

This is useful to insert into a pipeline that will keep updating a message over a set of events.

show-results-in-slack cljs

(show-results-in-slack handler
                       &
                       {:keys [result-type] :or {result-type "results"}})

request middleware will send a slack snippet containing the results in the current request. Mostly for debugging This request must already have been configured to send to a particular Slack channel or be a command handler request.

simple-message cljs

(simple-message o s)

send simple message as bot params o - command request or event s - string message

skip-if-not-default-branch cljs

(skip-if-not-default-branch handler)

skip-push-if-atomist-edited cljs

(skip-push-if-atomist-edited handler)

request middleware that checks whether a Push event contains a message with [atomist:edited]

handler chain stops if the message contains [atomist:edited] and otherwise continues

snippet-message cljs

(snippet-message o content-str filetype title)

send snippet as bot params o - command request or event content-str - content as string filetype - valid slack filetype title - string title

status cljs

(status handler)

middleware looks for :atomist/status in request and sends a status message on response topic

• fail if there is no valid :atomist/status in the response

stop-if-no-files-detected cljs

(stop-if-no-files-detected handler & {:keys [substr]})

this will halt on Repos that don't have any files matching a certain substr

trace cljs

(trace s)

transact cljs

(transact o coll)

transact the coll of entities using the response pubsub topic requires :sendreponse :correlation_id :team :api_version

transact-http-response cljs

(transact-http-response request response check? ->transaction)

params request response - http response check? - predicate for evaluating response ->transaction - build transaction data

update-if-exists cljs

(update-if-exists m k f)

update-in-if-exists cljs

(update-in-if-exists m ks f)

user cljs

(user o u)

set first message destination to user DM params o - command request or incoming event payload c - string name of user to DM

user-should-choose-one-linked-repo cljs

(user-should-choose-one-linked-repo handler)

request middleware when the request :linked-repos has >1 linked repo, force the user to choose if, on the other hand, the request has zero repos, stop and tell the user that this command should be run from a channel with at least one linked repo

validate-repo-in-graph cljs

(validate-repo-in-graph handler repo-name-fn)

request middleware ensure Repo referenced in a command is present in graph - if present, add it to the request with key :repo

with-github-check-run cljs

(with-github-check-run handler
                       &
                       {:keys [name default conclusion]
                        :or {conclusion :checkrun/conclusion}})

request should contain an :atomist/ref-with-sha but :atomist/datomic-refs will also transact the checkrun into our model options :name - checkrun name or keyword to extract name from request :default - default checkrun name if name is nil :conclusion - defaults to :checkrun/conlusion but can be a 1-arg function that will be called on the handler response

wrap-conditional-mw cljs

(wrap-conditional-mw predicate? mw & args)