Merge pull request #31 from Space48/improved-docs

Improved documentation on using cloud-seed

docs/firestore.md

@@ -0,0 +1,30 @@
+# Firestore invoked Functions
+
+This allows you to invoke functions in response to events within Firestore such as: write, create, update or delete.
+
+Parameters:
+
+- `type` must be `"firestore"`
+- `collection` the name of the firestore collection.
+- Optional: `event` can be one of: `write` (default), `create`, `update` or `delete`
+
+## Code sample
+
+```typescript
+import { EventFunction } from "@google-cloud/functions-framework/build/src/functions";
+import { GcpConfig } from "@space48/cloud-seed";
+
+const fn: EventFunction = (data) => {
+  console.log("This is a firestore triggered function", data);
+};
+
+export default fn;
+
+export const runtimeConfig: GcpConfig = {
+  cloud: "gcp",
+  type: "firestore",
+  collection: "myCollection",
+  // Optional event type (defaults to 'write').
+  event: "create"
+};
+```

docs/http.md

@@ -0,0 +1,20 @@
+# HTTP Invoked Functions
+
+## Code Sample:
+
+```typescript
+import { GcpConfig } from "@space48/cloud-seed";
+import { HttpFunction } from "@google-cloud/functions-framework/build/src/functions";
+
+const handler: HttpFunction = (req, res) => {
+  return res.status(200).send(JSON.stringify({ message: "Hello World!" }));
+};
+
+export default handler;
+
+export const runtimeConfig: GcpConfig = {
+  cloud: "gcp",
+  type: "http",
+  public: true, // Should it be pubically callable?
+};
+```

docs/index.md

@@ -0,0 +1,60 @@
+# Cloud Seed Documentation
+
+Welcome to Cloud Seed! A CLI tool for building serverless applications.
+
+## Getting started:
+
+```
+# Install globally on your machine:
+npm install -g @space48/cloud-seed
+
+# Install as a dev dependency.
+npm install -D @space48/cloud-seed
+```
+
+## Starting a new project:
+
+Add required dependencies:
+
+```
+npm init
+npm install -D @space48/cloud-seed @types/express @types/jest @types/node typescript
+npm install @google-cloud/functions-framework @google-cloud/secret-manager
+```
+
+Add build script to `package.json`:
+
+```diff
+  scripts: {
++    "build": "rimraff .build && cloud-seed build . --project=[YOUR_PROJECT_NAME]",
+    ...
+  },
+```
+
+Create your first function: `src/helloWorldHttp.ts`
+
+```typescript
+import { GcpConfig } from "@space48/cloud-seed";
+import { HttpFunction } from "@google-cloud/functions-framework/build/src/functions";
+
+const handler: HttpFunction = (req, res) => {
+  return res.status(200).send(JSON.stringify({ message: "Hello World!" }));
+};
+
+export default handler;
+
+export const runtimeConfig: GcpConfig = {
+  cloud: "gcp",
+  type: "http",
+  public: true,
+};
+```
+
+More information, see:
+
+- [Creating HTTP Functions](./http.md)
+- [Creating BigCommerce Webhooks invoked Functions](./webhooks.md)
+- [Creating PubSub Topics and Subscriptions](./pubsub.md)
+- [Creating Scheduled Functions](./scheduled.md)
+- [Creating Firestore triggered Functions](./firestore.md)
+- [Creating Secrets](./secrets.md)

docs/pubsub.md

@@ -0,0 +1,22 @@
+# PubSub invoked Functions
+
+If you want your function to be subscribed to a pubsub topic, you can use the `event` type in the runtimeConfig, which requires the `topicName` property which is a string defining the name of the topic you'd like to subscribe to. The pubsub topic will be created in terraform so should not already exist (unless theres another function subscribing to the same topic).
+
+## Code sample
+
+```typescript
+import { EventFunction } from "@google-cloud/functions-framework/build/src/functions";
+import { GcpConfig } from "@space48/cloud-seed";
+
+const fn: EventFunction (data) => {
+  console.log("This is a event triggered function", data);
+};
+
+export const runtimeConfig: GcpConfig = {
+  cloud: "gcp",
+  type: "event",
+  // By defining the topicName it will create to the topic for you.
+  topicName: "hello-world",
+};
+```
+

docs/scheduled.md

@@ -0,0 +1,22 @@
+# Scheduled Functions
+
+If you wish to have a function that is triggered by cron, you can use the `"schedule"` type for runtimeConfig which required the `schedule` property. The `schedule` property accepts a valid cron expression.
+
+## Code sample
+
+```typescript
+import { EventFunction } from "@google-cloud/functions-framework/build/src/functions";
+import { GcpConfig } from "@space48/cloud-seed";
+
+const fn: EventFunction = (data) => {
+  console.log("This is a scheduled triggered function", data);
+};
+
+export default fn;
+
+export const runtimeConfig: GcpConfig = {
+  cloud: "gcp",
+  type: "schedule",
+  schedule: "* * * * *",
+};
+```

docs/secrets.md

@@ -0,0 +1,12 @@
+# Secrets
+
+Secrets can be defined using a `secrets.json` file in the root of the project. The contents will look like this:
+
+```json
+[
+  "bigcommerce-access-token",
+  "name-of-my-secret-in-gcp"
+]
+```
+
+Each value in the array will create a secret in GCP Secret Manager. They will be populated with `INITIAL_VALUE` by default, this means you'll need to login and modify the secret within the GCP projects yourself to configure them with the correct value.

docs/webhooks.md

@@ -0,0 +1,57 @@
+# Configuring Bigcommerce Webhooks
+
+If you need to trigger your functions from a BigCommerce Webhook then you can do so by adding small piece of configuration into the `runtimeConfig` export. See below:
+
+```diff
+export const runtimeConfig: GcpConfig = {
+  cloud: "gcp",
+  type: "http",
+  public: true,
++  webhook: {
++    type: "bigcommerce",
++    scopes: ["store/customer/created"],
++  },
+};
+```
+
+As you can see the `webhook` object supports two properties: `type` and `scopes`.
+
+Currently the only supported value for `type` is `bigcommerce`.
+
+`scopes` is an array of BigCommerce event scopes you wish to listen for! Refer to the BigCommerce API documentation for more details.
+
+## Configuring the BigCommerce store
+
+To configure which BigCommerce store the webhooks are created for you will need to define the following environment variables:
+
+- `BIGCOMMERCE_STORE_HASH`
+- `BIGCOMMERCE_CLIENT_ID`
+- `BIGCOMMERCE_ACCESS_TOKEN`
+
+These environment variables will need to available when the `terraform plan` and `terraform apply` commands are executed as part of your deployment pipeline.
+
+
+
+### Complete code example:
+
+```typescript
+import { GcpConfig } from "@space48/cloud-seed";
+import { HttpFunction } from "@google-cloud/functions-framework/build/src/functions";
+
+const handler: HttpFunction = (req, res) => {
+  return res.status(200).send(JSON.stringify({ message: "ok" }));
+};
+
+export default handler;
+
+export const runtimeConfig: GcpConfig = {
+  cloud: "gcp",
+  type: "http",
+  public: true,
+  webhook: {
+    type: "bigcommerce",
+    scopes: ["store/customer/created"],
+  },
+};
+
+```