@useairfoil/producer-salesforce 0.0.0-stage → 0.0.2

package/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# Salesforce producer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Syncs Salesforce records from one org: standard objects, custom objects, field
+history, and field definitions. It backfills each table, then polls business
+objects every 10 minutes and setup objects every hour. Salesforce has no signed
+webhooks, so there are none.
+
+| Resource                                                                                                                                                                                                                                                                    | What                                     |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| `accounts`, `account_contact_relations`, `account_team_members`, `contacts`, `leads`, `opportunities`, `opportunity_line_items`, `opportunity_contact_roles`, `opportunity_competitors`, `opportunity_team_members`, `opportunity_splits`, `partners`, `forecasting_quotas` | Sales                                    |
+| `quotes`, `quote_line_items`, `contracts`, `contract_contact_roles`, `orders`, `order_items`                                                                                                                                                                                | Quotes and orders                        |
+| `products`, `pricebooks`, `pricebook_entries`, `assets`, `asset_relationships`                                                                                                                                                                                              | Catalog and assets                       |
+| `campaigns`, `campaign_members`, `campaign_member_statuses`, `individuals`, `contact_point_emails`, `contact_point_phones`                                                                                                                                                  | Marketing                                |
+| `cases`, `case_comments`, `case_contact_roles`, `case_team_members`, `entitlements`, `service_contracts`, `contract_line_items`, `solutions`, `email_messages`, `email_message_relations`, `live_chat_transcripts`, `messaging_sessions`, `macros`, `quick_texts`           | Service                                  |
+| `work_orders`, `work_order_line_items`, `service_appointments`, `service_resources`, `service_territories`, `assigned_resources`, `resource_absences`, `locations`, `product_items`                                                                                         | Field Service                            |
+| `tasks`, `task_relations`, `events`, `event_relations`, `notes`, `attachments`, `feed_items`, `feed_comments`, `topics`, `topic_assignments`                                                                                                                                | Activities                               |
+| `account_history`, `contact_history`, `lead_history`, `case_history`, `opportunity_history`, `opportunity_field_history`                                                                                                                                                    | Field history                            |
+| `users`, `user_roles`, `profiles`, `permission_sets`, `permission_set_assignments`, `groups`, `group_members`, `collaboration_groups`, `collaboration_group_members`, `record_types`, `business_hours`, `holidays`, `periods`, `organization`, `folders`, `documents`       | Users and setup                          |
+| `duplicate_record_sets`, `duplicate_record_items`                                                                                                                                                                                                                           | Duplicate rules                          |
+| `custom_objects`                                                                                                                                                                                                                                                            | Records of every custom object (`*__c`)  |
+| `object_fields`                                                                                                                                                                                                                                                             | Field definitions, to name `fields` keys |
+
+## Config
+
+| Variable                   | Required | Default |
+| -------------------------- | -------- | ------- |
+| `SALESFORCE_DOMAIN`        | yes      | none    |
+| `SALESFORCE_CLIENT_ID`     | yes      | none    |
+| `SALESFORCE_CLIENT_SECRET` | yes      | none    |
+
+`SALESFORCE_DOMAIN` is the org's My Domain host, such as
+`acme.my.salesforce.com`. Sandboxes work too.
+
+## Setup
+
+1. Pick the user the connector runs as. A user with the Salesforce Integration
+   license works. Give it API Enabled, read access to the synced objects, and
+   View All Data. Without View All Data, records outside its sharing are
+   missed.
+2. In Setup, open **External Client App Manager → New External Client App**.
+   Turn on OAuth with the `api` scope and **Enable Client Credentials Flow**.
+   The callback URL isn't used.
+3. In the app's **Policies → OAuth Policies**, turn on the client credentials
+   flow and set **Run As** to the user from step 1.
+4. Under **Settings → OAuth Settings → Consumer Key and Secret**, copy the key
+   and secret to `SALESFORCE_CLIENT_ID` and `SALESFORCE_CLIENT_SECRET`.
+
+One app and domain read one org, so run one connector per org.
+
+## API version
+
+The connector uses REST API `v68.0` (Winter '27).
+
+## Data
+
+- Object tables keep every non-null field the user can read in `fields`, by API
+  name, as strings: text as is, numbers and booleans as JSON text, and dates as
+  Salesforce sends them. New custom fields show up on their own.
+  `object_fields` has each field's label, type, and picklist values.
+- Address and location fields are left out, because their parts (such as
+  `BillingCity`) are fields too. So are binary fields, such as attachment
+  bodies.
+- `created_at` is `CreatedDate` and `updated_at` is `SystemModstamp`. Both are
+  null on objects without them, such as history objects.
+- `custom_objects` holds every custom object. `object` says which, such as
+  `Invoice__c`.
+- A deleted or merged-away record gets `_deleted`. A restored record comes
+  back.
+- Contacts, leads, users, individuals, contact points, cases, emails, chat and
+  messaging transcripts, feed items, notes, tasks, and events hold names,
+  emails, phone numbers, addresses, and message bodies. Treat them as customer
+  data.
+
+## Demo data
+
+`pnpm demo --size 128MiB` writes made-up Salesforce data without Salesforce
+credentials. See the Connector Kit README for the flags and the variables it
+needs.
+
+Each account has contacts, opportunities with products, quotes, history, and
+splits, and, once won, a contract, an order, assets, a service contract with
+entitlements, an install visit, and an onboarding project in `custom_objects`.
+Customers open cases with comments, emails, and chats. Accounts also get tasks,
+events, notes, Chatter posts, and a lead. The org setup is written once and
+doesn't grow with the size: users, roles, profiles, permissions, groups, the
+catalog and price book, campaigns, service resources, and `object_fields`.
+
+## Limits
+
+- Salesforce lists changes for the last 30 days and deletes for the last 15.
+  A connector stopped for more than 15 days fails, and those tables need a new
+  backfill.
+- Formula fields that read other records only change in a row when the record
+  itself changes.
+- `permission_sets`, `permission_set_assignments`, and `collaboration_groups`
+  can't be replicated, so they're read in full every hour, and removed rows
+  stay.
+- An org without a feature, such as Quotes or Field Service, or a user without
+  access, leaves that table in error. The other tables keep syncing.
+- Every table costs at least 2 API calls per poll. With every table on, that's
+  about 23,000 calls a day. A Developer Edition org has 15,000, so turn on only
+  the tables you need there.

package/dist/index.d.mts

@@ -0,0 +1,228 @@
+import { ObjectSpec, SalesforceConfig, SalesforceConfigDef, manifest, objects } from "./manifest.mjs";
+import { Auth, ConnectorError } from "@useairfoil/connector-kit";
+import { Config, Context, Effect, Layer, Schema } from "effect";
+import { HttpClient } from "effect/http";
+declare namespace auth_d_exports {
+  export { SalesforceAuth, SalesforceAuthService, layer$2 as layer, make$2 as make };
+}
+type SalesforceAuthConfig = Pick<SalesforceConfig, "domain" | "clientId" | "clientSecret">;
+type SalesforceAuthService = Auth.TokenCache<ConnectorError>;
+declare const SalesforceAuth_base: Context.ServiceClass<SalesforceAuth, "@useairfoil/producer-salesforce/SalesforceAuth", SalesforceAuthService>;
+declare class SalesforceAuth extends SalesforceAuth_base {}
+declare const make$2: (config: SalesforceAuthConfig) => Effect.Effect<Auth.TokenCache<ConnectorError>, never, HttpClient.HttpClient>;
+declare const layer$2: (config: SalesforceAuthConfig) => Layer.Layer<SalesforceAuth, never, HttpClient.HttpClient>;
+declare namespace client_d_exports {
+  export { SALESFORCE_API_VERSION, SalesforceClient, SalesforceClientService, SalesforceResponse, layer$1 as layer, layerConfig$1 as layerConfig, make$1 as make };
+}
+declare const SALESFORCE_API_VERSION = "68.0";
+type SalesforceResponse<A> = {
+  readonly body: A;
+  /** When the response arrived. Used as the row version. */
+  readonly fetchedAt: Date;
+};
+type SalesforceClientService = {
+  /** Paths are relative to `/services/data/v68.0`. */
+  readonly get: <A>(schema: Schema.Decoder<A>, path: string, params?: Readonly<Record<string, string>>) => Effect.Effect<SalesforceResponse<A>, ConnectorError>;
+  readonly post: <A>(schema: Schema.Decoder<A>, path: string, body: unknown) => Effect.Effect<SalesforceResponse<A>, ConnectorError>;
+};
+declare const SalesforceClient_base: Context.ServiceClass<SalesforceClient, "@useairfoil/producer-salesforce/SalesforceClient", SalesforceClientService>;
+declare class SalesforceClient extends SalesforceClient_base {}
+declare const make$1: (config: {
+  readonly domain: string;
+  readonly clientId: string;
+  readonly clientSecret: import("effect/Redacted").Redacted<string>;
+}) => Effect.Effect<SalesforceClientService, never, SalesforceAuth | HttpClient.HttpClient>;
+declare const layer$1: (config: SalesforceConfig) => Layer.Layer<SalesforceClient, never, HttpClient.HttpClient>;
+declare const layerConfig$1: (config: Config.Wrap<SalesforceConfig>) => Layer.Layer<SalesforceClient, Config.ConfigError, HttpClient.HttpClient>;
+declare namespace connector_d_exports {
+  export { SalesforceConfig, SalesforceConfigDef, SalesforceConnector, SalesforceConnectorRuntime, layer, layerConfig, make, manifest };
+}
+declare const make: () => Effect.Effect<import("@useairfoil/connector-kit").ConnectorDefinition<readonly [...import("@useairfoil/connector-kit").ResourceDefinition<import("effect/Schema").Struct<{
+  id: import("effect/Schema").String;
+  version: import("effect/Schema").Date;
+  created_at: import("effect/Schema").NullOr<import("effect/Schema").Date>;
+  updated_at: import("effect/Schema").NullOr<import("effect/Schema").Date>;
+  fields: import("effect/Schema").$ReadonlyMap<import("effect/Schema").String, import("effect/Schema").String>;
+  _deleted: import("effect/Schema").optional<import("effect/Schema").Boolean>;
+}> & import("@useairfoil/connector-kit").Identified<"id">, never, never, string, "version">[], import("@useairfoil/connector-kit").ResourceDefinition<import("effect/Schema").Struct<{
+  readonly object: import("effect/Schema").String;
+  readonly id: import("effect/Schema").String;
+  readonly version: import("effect/Schema").Date;
+  readonly created_at: import("effect/Schema").NullOr<import("effect/Schema").Date>;
+  readonly updated_at: import("effect/Schema").NullOr<import("effect/Schema").Date>;
+  readonly fields: import("effect/Schema").$ReadonlyMap<import("effect/Schema").String, import("effect/Schema").String>;
+  readonly _deleted: import("effect/Schema").optional<import("effect/Schema").Boolean>;
+}> & import("@useairfoil/connector-kit").Identified<"id">, never, never, "custom_objects", "version">, import("@useairfoil/connector-kit").ResourceDefinition<import("effect/Schema").Struct<{
+  readonly id: import("effect/Schema").String;
+  readonly version: import("effect/Schema").Date;
+  readonly object: import("effect/Schema").String;
+  readonly name: import("effect/Schema").String;
+  readonly label: import("effect/Schema").String;
+  readonly type: import("effect/Schema").String;
+  readonly custom: import("effect/Schema").Boolean;
+  readonly calculated: import("effect/Schema").Boolean;
+  readonly nillable: import("effect/Schema").Boolean;
+  readonly length: import("effect/Schema").BigInt;
+  readonly precision: import("effect/Schema").BigInt;
+  readonly scale: import("effect/Schema").BigInt;
+  readonly reference_to: import("effect/Schema").$Array<import("effect/Schema").String>;
+  readonly picklist_values: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+    readonly value: import("effect/Schema").String;
+    readonly label: import("effect/Schema").NullOr<import("effect/Schema").String>;
+    readonly active: import("effect/Schema").Boolean;
+  }>>;
+}> & import("@useairfoil/connector-kit").Identified<"id">, never, never, "object_fields", "version">], readonly [...import("@useairfoil/connector-kit").ResourceDefinition<import("effect/Schema").Struct<{
+  id: import("effect/Schema").String;
+  version: import("effect/Schema").Date;
+  created_at: import("effect/Schema").NullOr<import("effect/Schema").Date>;
+  updated_at: import("effect/Schema").NullOr<import("effect/Schema").Date>;
+  fields: import("effect/Schema").$ReadonlyMap<import("effect/Schema").String, import("effect/Schema").String>;
+  _deleted: import("effect/Schema").optional<import("effect/Schema").Boolean>;
+}> & import("@useairfoil/connector-kit").Identified<"id">, never, never, string, "version">[], import("@useairfoil/connector-kit").ResourceDefinition<import("effect/Schema").Struct<{
+  readonly object: import("effect/Schema").String;
+  readonly id: import("effect/Schema").String;
+  readonly version: import("effect/Schema").Date;
+  readonly created_at: import("effect/Schema").NullOr<import("effect/Schema").Date>;
+  readonly updated_at: import("effect/Schema").NullOr<import("effect/Schema").Date>;
+  readonly fields: import("effect/Schema").$ReadonlyMap<import("effect/Schema").String, import("effect/Schema").String>;
+  readonly _deleted: import("effect/Schema").optional<import("effect/Schema").Boolean>;
+}> & import("@useairfoil/connector-kit").Identified<"id">, never, never, "custom_objects", "version">, import("@useairfoil/connector-kit").ResourceDefinition<import("effect/Schema").Struct<{
+  readonly id: import("effect/Schema").String;
+  readonly version: import("effect/Schema").Date;
+  readonly object: import("effect/Schema").String;
+  readonly name: import("effect/Schema").String;
+  readonly label: import("effect/Schema").String;
+  readonly type: import("effect/Schema").String;
+  readonly custom: import("effect/Schema").Boolean;
+  readonly calculated: import("effect/Schema").Boolean;
+  readonly nillable: import("effect/Schema").Boolean;
+  readonly length: import("effect/Schema").BigInt;
+  readonly precision: import("effect/Schema").BigInt;
+  readonly scale: import("effect/Schema").BigInt;
+  readonly reference_to: import("effect/Schema").$Array<import("effect/Schema").String>;
+  readonly picklist_values: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+    readonly value: import("effect/Schema").String;
+    readonly label: import("effect/Schema").NullOr<import("effect/Schema").String>;
+    readonly active: import("effect/Schema").Boolean;
+  }>>;
+}> & import("@useairfoil/connector-kit").Identified<"id">, never, never, "object_fields", "version">]>, never, SalesforceClient>;
+type SalesforceConnectorRuntime = Effect.Success<ReturnType<typeof make>>;
+declare const SalesforceConnector_base: Context.ServiceClass<SalesforceConnector, "@useairfoil/producer-salesforce/SalesforceConnector", import("@useairfoil/connector-kit").ConnectorDefinition<readonly [...import("@useairfoil/connector-kit").ResourceDefinition<import("effect/Schema").Struct<{
+  id: import("effect/Schema").String;
+  version: import("effect/Schema").Date;
+  created_at: import("effect/Schema").NullOr<import("effect/Schema").Date>;
+  updated_at: import("effect/Schema").NullOr<import("effect/Schema").Date>;
+  fields: import("effect/Schema").$ReadonlyMap<import("effect/Schema").String, import("effect/Schema").String>;
+  _deleted: import("effect/Schema").optional<import("effect/Schema").Boolean>;
+}> & import("@useairfoil/connector-kit").Identified<"id">, never, never, string, "version">[], import("@useairfoil/connector-kit").ResourceDefinition<import("effect/Schema").Struct<{
+  readonly object: import("effect/Schema").String;
+  readonly id: import("effect/Schema").String;
+  readonly version: import("effect/Schema").Date;
+  readonly created_at: import("effect/Schema").NullOr<import("effect/Schema").Date>;
+  readonly updated_at: import("effect/Schema").NullOr<import("effect/Schema").Date>;
+  readonly fields: import("effect/Schema").$ReadonlyMap<import("effect/Schema").String, import("effect/Schema").String>;
+  readonly _deleted: import("effect/Schema").optional<import("effect/Schema").Boolean>;
+}> & import("@useairfoil/connector-kit").Identified<"id">, never, never, "custom_objects", "version">, import("@useairfoil/connector-kit").ResourceDefinition<import("effect/Schema").Struct<{
+  readonly id: import("effect/Schema").String;
+  readonly version: import("effect/Schema").Date;
+  readonly object: import("effect/Schema").String;
+  readonly name: import("effect/Schema").String;
+  readonly label: import("effect/Schema").String;
+  readonly type: import("effect/Schema").String;
+  readonly custom: import("effect/Schema").Boolean;
+  readonly calculated: import("effect/Schema").Boolean;
+  readonly nillable: import("effect/Schema").Boolean;
+  readonly length: import("effect/Schema").BigInt;
+  readonly precision: import("effect/Schema").BigInt;
+  readonly scale: import("effect/Schema").BigInt;
+  readonly reference_to: import("effect/Schema").$Array<import("effect/Schema").String>;
+  readonly picklist_values: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+    readonly value: import("effect/Schema").String;
+    readonly label: import("effect/Schema").NullOr<import("effect/Schema").String>;
+    readonly active: import("effect/Schema").Boolean;
+  }>>;
+}> & import("@useairfoil/connector-kit").Identified<"id">, never, never, "object_fields", "version">], readonly [...import("@useairfoil/connector-kit").ResourceDefinition<import("effect/Schema").Struct<{
+  id: import("effect/Schema").String;
+  version: import("effect/Schema").Date;
+  created_at: import("effect/Schema").NullOr<import("effect/Schema").Date>;
+  updated_at: import("effect/Schema").NullOr<import("effect/Schema").Date>;
+  fields: import("effect/Schema").$ReadonlyMap<import("effect/Schema").String, import("effect/Schema").String>;
+  _deleted: import("effect/Schema").optional<import("effect/Schema").Boolean>;
+}> & import("@useairfoil/connector-kit").Identified<"id">, never, never, string, "version">[], import("@useairfoil/connector-kit").ResourceDefinition<import("effect/Schema").Struct<{
+  readonly object: import("effect/Schema").String;
+  readonly id: import("effect/Schema").String;
+  readonly version: import("effect/Schema").Date;
+  readonly created_at: import("effect/Schema").NullOr<import("effect/Schema").Date>;
+  readonly updated_at: import("effect/Schema").NullOr<import("effect/Schema").Date>;
+  readonly fields: import("effect/Schema").$ReadonlyMap<import("effect/Schema").String, import("effect/Schema").String>;
+  readonly _deleted: import("effect/Schema").optional<import("effect/Schema").Boolean>;
+}> & import("@useairfoil/connector-kit").Identified<"id">, never, never, "custom_objects", "version">, import("@useairfoil/connector-kit").ResourceDefinition<import("effect/Schema").Struct<{
+  readonly id: import("effect/Schema").String;
+  readonly version: import("effect/Schema").Date;
+  readonly object: import("effect/Schema").String;
+  readonly name: import("effect/Schema").String;
+  readonly label: import("effect/Schema").String;
+  readonly type: import("effect/Schema").String;
+  readonly custom: import("effect/Schema").Boolean;
+  readonly calculated: import("effect/Schema").Boolean;
+  readonly nillable: import("effect/Schema").Boolean;
+  readonly length: import("effect/Schema").BigInt;
+  readonly precision: import("effect/Schema").BigInt;
+  readonly scale: import("effect/Schema").BigInt;
+  readonly reference_to: import("effect/Schema").$Array<import("effect/Schema").String>;
+  readonly picklist_values: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+    readonly value: import("effect/Schema").String;
+    readonly label: import("effect/Schema").NullOr<import("effect/Schema").String>;
+    readonly active: import("effect/Schema").Boolean;
+  }>>;
+}> & import("@useairfoil/connector-kit").Identified<"id">, never, never, "object_fields", "version">]>>;
+declare class SalesforceConnector extends SalesforceConnector_base {}
+declare const layer: (config: SalesforceConfig) => Layer.Layer<SalesforceConnector, never, import("effect/http/HttpClient").HttpClient>;
+declare const layerConfig: (config: Config.Wrap<SalesforceConfig>) => Layer.Layer<SalesforceConnector, Config.ConfigError, import("effect/http/HttpClient").HttpClient>;
+//#endregion
+//#region src/schemas/object-fields.d.ts
+export declare const ObjectFieldSchema: Schema.Struct<{
+  readonly id: Schema.String;
+  readonly version: Schema.Date;
+  readonly object: Schema.String;
+  readonly name: Schema.String;
+  readonly label: Schema.String;
+  readonly type: Schema.String;
+  readonly custom: Schema.Boolean;
+  readonly calculated: Schema.Boolean;
+  readonly nillable: Schema.Boolean;
+  readonly length: Schema.BigInt;
+  readonly precision: Schema.BigInt;
+  readonly scale: Schema.BigInt;
+  readonly reference_to: Schema.$Array<Schema.String>;
+  readonly picklist_values: Schema.$Array<Schema.Struct<{
+    readonly value: Schema.String;
+    readonly label: Schema.NullOr<Schema.String>;
+    readonly active: Schema.Boolean;
+  }>>;
+}> & import("@useairfoil/connector-kit").Identified<"id">;
+type ObjectField = Schema.Schema.Type<typeof ObjectFieldSchema>;
+//#endregion
+//#region src/schemas/objects.d.ts
+export declare const objectSchema: (object: string) => Schema.Struct<{
+  id: Schema.String;
+  version: Schema.Date;
+  created_at: Schema.NullOr<Schema.Date>;
+  updated_at: Schema.NullOr<Schema.Date>;
+  fields: Schema.$ReadonlyMap<Schema.String, Schema.String>;
+  _deleted: Schema.optional<Schema.Boolean>;
+}> & import("@useairfoil/connector-kit").Identified<"id">;
+type ObjectRow = Schema.Schema.Type<ReturnType<typeof objectSchema>>;
+export declare const CustomObjectSchema: Schema.Struct<{
+  readonly object: Schema.String;
+  readonly id: Schema.String;
+  readonly version: Schema.Date;
+  readonly created_at: Schema.NullOr<Schema.Date>;
+  readonly updated_at: Schema.NullOr<Schema.Date>;
+  readonly fields: Schema.$ReadonlyMap<Schema.String, Schema.String>;
+  readonly _deleted: Schema.optional<Schema.Boolean>;
+}> & import("@useairfoil/connector-kit").Identified<"id">;
+type CustomObject = Schema.Schema.Type<typeof CustomObjectSchema>;
+//#endregion
+export { type CustomObject, type ObjectField, type ObjectRow, type ObjectSpec, client_d_exports as SalesforceClient, type SalesforceConfig, connector_d_exports as SalesforceConnector, manifest, objects };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,3 @@
+import { manifest, objects } from "./manifest.mjs";
+import { a as CustomObjectSchema, i as ObjectFieldSchema, n as connector_exports, o as objectSchema, s as client_exports } from "./src-C7uqtDzN.mjs";
+export { CustomObjectSchema, ObjectFieldSchema, client_exports as SalesforceClient, connector_exports as SalesforceConnector, manifest, objectSchema, objects };

package/dist/main.d.mts

@@ -0,0 +1 @@
+export {}