npm package: @simpleview/sv-act-on-client
Description: Client for communicating with sv-act-on
Author: Colin Booen
Latest version: 1.2.1

# sv-act-on-client

Client for communication with the `sv-act-on` GraphQL system.

It is build in TypeScript and has one peer dependency of `@simpleview/sv-graphql-client`.

## OS Support

The expectation is that this application will be installed in Linux using [sv-kubernetes](https://github.com/simpleviewinc/sv-kubernetes/).

## Prerequisites

* [sv-graphql-client](https://github.com/simpleviewinc/sv-graphql-client/)

## Install

Using npm:
```bash
npm install @simpleview/sv-act-on-client
```

Using yarn:
```bash
yarn install @simpleview/sv-act-on-client
```

## Update

To update to the latest version, rerun the install command.

## Authentication Requirements

Interactions with `sv-act-on` require authentication as a Simpleview user.

Use a Google Service Account when interacting with the service on behalf of a product.

```js
const { AuthPrefix } = require("@simpleview/sv-auth-client");
const { GraphServer } = require("@simpleview/sv-graphql-client");

async function serviceAccountToken() {
	const service_account = JSON.parse(SERVICE_ACCOUNT_JSON);

	const { auth } = new GraphServer({
		graphUrl: AUTH_GRAPHQL_URL,
		prefixes: [AuthPrefix]
	});

	// authorize the service_account return the token
	const { token } = await auth.login_service_account({
		input: {
			email: service_account.client_email,
			private_key: service_account.private_key
		},
		fields: `
			success
			token
		`
	});

	return token;
}
```

The `token` should be added to the `context` for each function call.

## Implementation & Usage

To see the input parameters and output fields of an endpoint, view the Schema in the GraphQL Explorer at https://graphql.simpleviewinc.com/ for the corresponding GraphQL query.

## ActOnPrefix

`ActOnPrefix` can be loaded into the `sv-graphql-client` `GraphServer` to use as a client library for accessing `act-on` in GraphQL.

JavaScript:
```js
const { ActOnPrefix } = require("@simpleview/sv-act-on-client");
const { GraphServer } = require("@simpleview/sv-graphql-client");

module.exports = new GraphServer({ graphUrl: GRAPHQL_URL, prefixes: [ActOnPrefix] });
```

TypeScript:
```ts
import { ActOnPrefix } from "@simpleview/sv-act-on-client";
import { GraphServer } from "@simpleview/sv-graphql-client";

export default new GraphServer({ graphUrl: GRAPHQL_URL, prefixes: [ActOnPrefix] });
```

Where you are making server requests:

JavaScript:
```js
const { act_on } = require("./actOnGraphServer");
```

TypeScript:
```ts
import { act_on } from "./actOnGraphServer";
```

### ActOnPrefix.aws_upload

This method wraps the `act_on.aws_upload` GraphQL mutation.

```js
const result = act_on.aws_upload({
	fields: "success message",
	input: {
		name: "path/to/file",
		url: "https://your_file_host.com/file.csv.gz",
		content_encoding: "gzip"
	},
	context: {
		acct_id: "your_acct_id",
		token // from serviceAccountToken call
	}
});
```

### ActOnPrefix.contact

This method wraps the `act_on.contact` GraphQL query.

```js
const result = act_on.contact({
	fields: "id first_name last_name",
	input: {
		email: "test1@test.com"
	},
	context: {
		acct_id: "your_acct_id",
		token // from serviceAccountToken call
	}
});
```

### ActOnPrefix.contacts_create

This method wraps the `act_on.contacts_create` GraphQL mutation.

```js
const result = act_on.contacts_create({
	fields: "success message id",
	input: {
		email: "test1@test.com"
	},
	context: {
		acct_id: "your_acct_id",
		token // from serviceAccountToken call
	}
});
```

### ActOnPrefix.contacts_update

This method wraps the `act_on.contacts_update` GraphQL mutation.

```js
const result = act_on.contacts_update({
	fields: "success message ids",
	input: {
		email: "test1@test.com",
		contact: {
			first_name: "Terry"
		}
	},
	context: {
		acct_id: "your_acct_id",
		token // from serviceAccountToken call
	}
});
```

### ActOnPrefix.contacts_delete

This method wraps the `act_on.contacts_delete` GraphQL mutation.

```js
const result = act_on.contacts_delete({
	fields: "success message",
	input: {
		email: "test1@test.com"
	},
	context: {
		acct_id: "your_acct_id",
		token // from serviceAccountToken call
	}
});
```

### ActOnPrefix.contact_report_activity

This method wraps the `act_on.contact_report_activity` GraphQL query.

```js
const result = act_on.contact_report_activity({
	fields: `
		first_outbound
		last_outbound
		first_inbound
		last_inbound
		entry_months_available
		action_counts {
			message_send
		}
		entries {
			id
			bin
			date
			what
		}
	`,
	input: {
		email: "test0@test.com"
	},
	context: {
		acct_id: "your_acct_id",
		token // from serviceAccountToken call
	}
});
```

### ActOnPrefix.contact_report_scores

This method wraps the `act_on.contact_report_scores` GraphQL query.

```js
const result = act_on.contact_report_scores({
	fields: "id name score",
	input: {
		email: "test0@test.com"
	},
	context: {
		acct_id: "your_acct_id",
		token // from serviceAccountToken call
	}
});
```

### ActOnPrefix.contact_report_segments

This method wraps the `act_on.contact_report_segments` GraphQL query.

```js
const result = act_on.contact_report_segments({
	fields: "id name",
	input: {
		email: "test0@test.com"
	},
	context: {
		acct_id: "your_acct_id",
		token // from serviceAccountToken call
	}
});
```

### ActOnPrefix.contact_subscriptions

This method wraps the `act_on.contact_subscriptions` GraphQL query.

```js
const result = act_on.contact({
	fields: "count docs { id name description }",
	input: {
		email: "test1@test.com"
	},
	context: {
		acct_id: "your_acct_id",
		token // from serviceAccountToken call
	}
});
```

### ActOnPrefix.contact_subscriptions_update

This method wraps the `act_on.contact_subscriptions_update` GraphQL mutation.

```js
const result = await act_on.contact_subscriptions_update({
	fields: "success message",
	input: {
		email: "test0@test.com",
		category: "Going Places",
		action: "optout"
	},
	context: {
		acct_id: "your_acct_id",
		token // from serviceAccountToken call
	}
});
```

### ActOnPrefix.subscription_categories

This method wraps the `act_on.subscription_categories` GraphQL query.

```js
const result = await act_on.subscription_categories({
	fields: `
		count
		docs {
			id
			acct_id
			name
			description
			header_id
			header_name
		}
	`,
	context: {
		acct_id: "your_acct_id",
		token // from serviceAccountToken call
	}
});
```

### ActOnPrefix.segments

This method wraps the `act_on.segments` GraphQL query.

```js
const result = act_on.segments({
	fields: `
		id
		name
		type
		parent_id
		size
	`,
	input: {
		page: 1,
		page_size: 5
	},
	context: {
		acct_id: "your_acct_id",
		token // from serviceAccountToken call
	}
});
```

### ActOnPrefix.segments_create

This method wraps the `act_on.segments_create` GraphQL mutation.

```js
const result = act_on.segments_create({
	fields: "success message id",
	input: {
		name: "test segment 1"
	},
	context: {
		acct_id: "your_acct_id",
		token // from serviceAccountToken call
	}
});
```

### ActOnPrefix.segments_update

This method wraps the `act_on.segments_update` GraphQL mutation.

```js
const result = act_on.segments_update({
	fields: "success message",
	input: {
		id: "g-02ff",
		name: "test segment 1"
	},
	context: {
		acct_id: "your_acct_id",
		token // from serviceAccountToken call
	}
});
```

### ActOnPrefix.segments_delete

This method wraps the `act_on.segments_delete` GraphQL mutation.

```js
const result = act_on.segments_delete({
	fields: "success message",
	input: {
		id: "g-0382"
	},
	context: {
		acct_id: "your_acct_id",
		token // from serviceAccountToken call
	}
});
```

### ActOnPrefix.segment_contacts

This method wraps the `act_on.segment_contacts` GraphQL query.

```js
const result = act_on.segment_contacts({
	fields: "id first_name last_name",
	input: {
		segment_id: "q-0002"
	},
	context: {
		acct_id: "your_acct_id",
		token // from serviceAccountToken call
	}
});
```

### ActOnPrefix.segment_contacts_add

This method wraps the `act_on.segment_contacts_add` GraphQL mutation.

```js
const result = act_on.segment_contacts_add({
	fields: `
		success
		message
		results {
			success
			message
			id
			external_id
			object_type
		}
		errors {
			success
			message
			id
			external_id
			object_type
		}
	`,
	input: {
		segment_id: "g-0382",
		contacts: [
			{
				id: "e7cabdd5-1c95-40fd-9bfb-b3c1f4faf15f"
			},
			{
				id: "81bd7caf-24cc-4c44-bd8d-f30d7514617d"
			}
		]
	},
	context: {
		acct_id: "your_acct_id",
		token // from serviceAccountToken call
	}
});
```

### ActOnPrefix.segment_contacts_delete

This method wraps the `act_on.segment_contacts_delete` GraphQL mutation.

```js
const result = act_on.segment_contacts_delete({
	fields: `
		success
		message
		results {
			success
			message
			id
			external_id
			object_type
		}
		errors {
			success
			message
			id
			external_id
			object_type
		}
	`,
	input: {
		segment_id: "g-0382",
		contacts: [
			{
				id: "e7cabdd5-1c95-40fd-9bfb-b3c1f4faf15f"
			},
			{
				id: "81bd7caf-24cc-4c44-bd8d-f30d7514617d"
			}
		]
	},
	context: {
		acct_id: "your_acct_id",
		token // from serviceAccountToken call
	}
});
```

### ActOnPrefix.import_definition

This method wraps the `act_on.import_definition` GraphQL query.

```js
const result = act_on.import_definition({
	fields: `
		id
		name
		mappings {
			act_on_column
			csv_column
			data_format
			overwrite_existing_value
		}
		quote_character
		delimiter
		merge_strategy
		object_type
	`,
	input: {
		id: 12000
	},
	context: {
		acct_id: "your_acct_id",
		token // from serviceAccountToken call
	}
});
```

### ActOnPrefix.import_definitions

This method wraps the `act_on.import_definitions` GraphQL query.

```js
const result = act_on.import_definitions({
	fields: `
		count
		docs {
			id
			name
			mappings {
				act_on_column
				csv_column
				data_format
				overwrite_existing_value
			}
			quote_character
			delimiter
			merge_strategy
			object_type
		}
	`,
	context: {
		acct_id: "your_acct_id",
		token // from serviceAccountToken call
	}
});
```

### ActOnPrefix.import_definitions_create

This method wraps the `act_on.import_definitions_create` GraphQL mutation.

```js
const result = act_on.import_definitions_create({
	fields: "success message id",
	input: {
		name: "test",
		mappings: [
			{
				act_on_column: "E-mail Address",
				csv_column: "EMAIL"
			}
		]
	},
	context: {
		acct_id: "your_acct_id",
		token // from serviceAccountToken call
	}
});
```

### ActOnPrefix.import_definitions_update

This method wraps the `act_on.import_definitions_update` GraphQL mutation.

```js
const result = act_on.import_definitions_update({
	fields: "success message",
	input: {
		id: 12000,
		name: "test",
		mappings: [
			{
				act_on_column: "E-mail Address",
				csv_column: "EMAIL"
			}
		]
	},
	context: {
		acct_id: "your_acct_id",
		token // from serviceAccountToken call
	}
});
```

### ActOnPrefix.import_definitions_delete

This method wraps the `act_on.import_definitions_delete` GraphQL mutation.

```js
const result = act_on.import_definitions_delete({
	fields: "success message",
	input: {
		id: 12000
	},
	context: {
		acct_id: "your_acct_id",
		token // from serviceAccountToken call
	}
});
```

### ActOnPrefix.contacts_import

This method wraps the `act_on.contacts_import` GraphQL mutation.

```js
const result = act_on.contacts_import({
	fields: "success message id",
	input: {
		import_definition_id: 12000,
		cleanup_import_definition: true,
		csv_data: `"EMAIL"\n"test@test.com"`
	},
	context: {
		acct_id: "your_acct_id",
		token // from serviceAccountToken call
	}
});
```

### ActOnPrefix.contacts_import_status

This method wraps the `act_on.contacts_import_status` GraphQL query.

```js
const result = act_on.contacts_import_status({
	fields: `
		created
		updated
		failed
		rejected
		submitted
		unsubmitted
		status
		error
	`,
	input: {
		id: "1719501229904_0f59b6a5-9485-4791-a2a1-4481c8f632fa_39ea2dc5-c446-4b8b-98d9-5a8ec7f53a2f17493467619279168819.csv"
	},
	context: {
		acct_id: "your_acct_id",
		token // from serviceAccountToken call
	}
})
```

## Related Documentation

* [sv-graphql-client](https://github.com/simpleviewinc/sv-graphql-client/)
* [sv-act-on](https://github.com/simpleviewinc/sv-act-on/)

## Troubleshooting

For any assistance please reach out on the [sv-act-on](https://simpleview-workspace.slack.com/archives/C05TMLRG848) Slack channel.