First version of proposed changes

COMPONENT-API.md

@@ -0,0 +1,196 @@
+## Component API
+
+The component API borrows concepts and structure from frontend components, like those in [Vue.js](https://vuejs.org/) or [React](https://reactjs.org/).
+
+Components are Node.js modules that export an object with the following properties:
+
+```javascript
+module.exports = {
+  name: "cronjob", // required
+  version: "0.0.1", // required
+  props,
+  methods,
+  run(event) {
+    console.log("Run any Node.js code here");
+  }
+};
+```
+
+Components accept input via [props](#props), and can define [methods](#methods).
+
+### `name`
+
+The name of the component, a **string** which identifies components deployed to user's accounts.
+
+This name will show up in the Pipedream UI, in CLI output (for example, from `pd list` commands), etc.
+
+If the user deploys a component to their account, but a component with that name already exists, the component will be named using an incrementing integer suffix. For example, if you deploy a component with the name `my-component` twice, the second deployed component will be named `my-component-1`.
+
+#### Constraints
+
+Names of components should match the following pattern:
+
+```text
+[a-zA-Z0-9-_]+
+```
+
+For example, `my-awesome-component` and `my_2nd_great_component` are valid names, but `Hello, World!` is not.
+
+Names that don't match this pattern will be "slugified" when a user deploys the component, replacing invalid characters to fit the pattern's constraints. Users will see the slugified name when listing components deployed to their account. For example, a name of `Hello, World!` will get converted to `hello-world`.
+
+### `version`
+
+The version of a component, a **string**.
+
+There are no constraints on the version, but consider using [semantic versioning](https://semver.org/).
+
+### `run` method
+
+Each time a component is [invoked](#how-components-run) (for example, via HTTP request), its `run` method is called.
+
+The event that triggered the component is passed to `run`, so that you can access it within the method:
+
+```javascript
+async run(event) {
+  console.log(event)
+}
+```
+
+You can reference `this` within the `run` method. `this` refers to the component, and provides access to [props](#props), [methods](#methods), and Pipedream-provided functions like `this.$emit`.
+
+You can view logs produced by the `run` method in the **LOGS** section of the Pipedream UI for the component, or using the `pd logs` CLI command:
+
+```bash
+pd logs <deployed-component-name>
+```
+
+If the `run` method emits events using `this.$emit`, you can access the events in the **EVENTS** section of the Pipedream UI for the component, or using the `pd events` CLI command:
+
+```bash
+pd events <deployed-component-name>
+```
+
+### Referencing `this`
+
+`this` refers to the component, and provides access to [props](#props), [methods](#methods), and Pipedream-provided functions like `this.$emit`.
+
+#### Referencing props
+
+Props can be accessed using `this.<prop-name>`. For example, a `secret` prop:
+
+```javascript
+props: {
+  secret: "string"
+},
+```
+
+can be referenced using `this.secret`
+
+#### Referencing methods
+
+Methods can be accessed using `this.<method-name>`. For example, a `random` method:
+
+```javascript
+methods: {
+  random() {
+    return Math.random()
+  },
+}
+```
+
+can be run like so:
+
+```javascript
+const randomNum = this.random();
+```
+
+### Interfaces
+
+Interfaces are infrastructure abstractions provided by the Pipedream platform. They declare how a component is invoked — via HTTP request, run on a schedule, etc. — and therefore define the shape of the events it processes.
+
+Interfaces make it possible to work with HTTP servers or scheduled tasks using nothing more than props. Once you declare the interface for your component, Pipedream creates the infrastructure for that component when it's deployed. For example, if you deploy a component that uses the HTTP interface, Pipedream creates a unique HTTP endpoint URL for that component. HTTP requests to that endpoint invoke the component, executing its `run` method.
+
+Interfaces also provide methods. For example, the HTTP interface exposes a `respond` method that lets your component issue HTTP responses:
+
+```javascript
+// this.http references the HTTP interface for the component, as you'll see below
+this.http.respond({
+  status: 200,
+  headers: {
+    "X-My-Custom-Header": "test"
+  },
+  body: event // This can be any string, object, or Buffer
+});
+```
+
+You'll see how to declare the props for each interface, and how to use their methods, below.
+
+#### `$.interface.http`
+
+Interfaces are **attached** to components via props. To use the HTTP interface, declare a prop whose value is the string `$.interface.http`:
+
+```javascript
+props: {
+  http: "$.interface.http"
+},
+```
+
+Since you control the name of props in your component, you can name the prop anything you'd like. The example just uses the name `http` for clarity.
+
+With this prop declaration, a unique HTTP endpoint URL will be created for this component on deploy.
+
+##### Methods on the HTTP interface
+
+The HTTP interface exposes a `respond` method that lets your component issue HTTP responses. Assuming the prop for your HTTP interface is named `http`:
+
+```javascript
+props: {
+  http: "$.interface.http"
+},
+```
+
+you can run `this.http.respond` to respond to the client:
+
+```javascript
+this.http.respond({
+  status: 200,
+  headers: {
+    "X-My-Custom-Header": "test"
+  },
+  body: event // This can be any string, object, or Buffer
+});
+```
+
+#### `$.interface.timer`
+
+### `props`
+
+### `methods`
+
+### `this.$emit`
+
+### `$.service.db`
+
+#### `set` method
+
+#### `get` method
+
+## How components run
+
+A component is triggered, or invoked, by events sent its interface.
+
+For example, a component configured to accept HTTP requests using `$.interface.http` runs on each HTTP request sent to its endpoint URL.
+
+A component using `$.interface.timer` runs according to its schedule.
+
+Each time a component is invoked, its `run` method is called. You can view logs produced by this method in the **LOGS** section of the Pipedream UI for the component, or using the `pd logs` CLI command:
+
+```bash
+pd logs <deployed-component-name>
+```
+
+If the `run` method emits events using `this.$emit`, you can access the events in the **EVENTS** section of the Pipedream UI for the component, or using the `pd events` CLI command:
+
+```bash
+pd events <deployed-component-name>
+```

README.md

@@ -7,32 +7,52 @@
 
 ## Usage
 
-To install the Pipedream CLI, run:
+Install the Pipedream CLI:
 
 ```bash
 curl https://cli.pipedream.com/install | sh
 ```
 
-Then create an event stream:
+Then deploy a component:
 
 ```bash
-pd deploy   # prompts you to select a source and pass required options
+pd deploy   # prompts you to select a component and pass required options
 ```
 
-Check out our guide on [HTTP Event Sources](/apps/http/), or review [the docs](https://docs.pipedream.com) for a detailed overview of the CLI, and for more examples of deploying specific components.
+Check out our quickstart for [HTTP Event Sources](/apps/http/) or review [the docs](#docs) to learn more.
+
+## What are components?
+
+[Pipedream components](API.md) are Node.js modules that run code on specific events: HTTP requests, timers, and more. Components are meant to be small, self-contained, and reusable. Components run on Pipedream's infrastructure.
+
+Components are [**free to run**](#pricing) and [simple to learn](API.md). They come with a built-in key-value store, a props interface, [and more](API.md).
+
+Components can **emit** events, which can be retrieved programmatically using the [Pipedream CLI](https://docs.pipedream.com/cli/reference/), [REST API](https://docs.pipedream.com/api/reference/), or [SSE](https://docs.pipedream.com/event-sources/consuming-events/#sse). Components that emit events are called **event sources**.
 
 ## What are Event Sources?
 
-**Event sources turn any API into an event stream**.
+**Event sources turn any API into an event stream, and turn any event stream into an API**.
+
+Sources collect data from services like Github, Stripe, the bitcoin blockchain, RSS feeds, and more. They emit new events produced by the service, which can be consumed by any application via [REST API](https://docs.pipedream.com/api/reference/) or SSE.
+
+Event sources run on Pipedream's infrastructure, but you can retrieve emitted events in your own app using the [Pipedream CLI](https://docs.pipedream.com/cli/reference/), [REST API](https://docs.pipedream.com/api/reference/), or [SSE stream](https://docs.pipedream.com/event-sources/consuming-events/#sse) tied to your source.
+
+## Docs
+
+- [What are Event Sources?](https://docs.pipedream.com/event-sources/)
+- [HTTP Event Sources Quickstart](https://github.com/PipedreamHQ/pipedream/tree/master/apps/http)
+- [REST API Reference](https://docs.pipedream.com/api/reference/)
+- [SSE](https://docs.pipedream.com/event-sources/consuming-events/#sse)
+- [CLI Reference](https://docs.pipedream.com/cli/reference/)
 
-Sources collect data from services like Github, Stripe, the bitcoin blockchain, RSS feeds, and more. They emit new events produced by the service, which can be consumed by any application via HTTP API or SSE.
+## Component API
 
-Event sources run on Pipedream's infrastructure, but you can retrieve emitted events in your own apps using the Pipedream CLI, HTTP API, or SSE stream tied to your source.
+See [the component API docs](API.md).
 
-## Documentation
+## Found a Bug? Have a Feature to suggest?
 
-For details on how to use Pipedream CLI and the rest of the Pipedream platform, please review our [documentation](https://docs.pipedream.com).
+Any bugs or feature requests for specific components can be raised in this repo as new Github issues or pull requests.
 
-## Found a Bug? Want to Suggest a Feature?
+Pipedream also operates [a roadmap](https://github.com/PipedreamHQ/roadmap) to solicit feature requests for the Pipedream platform at large (the [pipedream.com UI](https://pipedream.com), [workflows](https://docs.pipedream.com/workflows/), the CLI, etc).
 
-Any bugs or feature requests for specific components, or for the Pipedream CLI, can be raised here as new Github issues.
+You can always [reach out to our team](https://docs.pipedream.com/support/) - we're happy to discuss feedback or help fix a bug.