Turn a web form into an opportunity

BASE="${FILMO_BASE_URL:-https://app.filmo.io}"
curl -sS "$BASE/api/v1/account" \
  -H "Authorization: Bearer $FILMO_API_KEY"

import { filmo } from "./filmo-client.mjs";

const res = await filmo("GET", "/api/v1/account");
if (!res.ok) throw new Error("getAccount " + res.status + " " + res.body?.code);

const { timezone, currency, addons, trial, apiKey } = res.body.data;
console.log({ timezone, currency, addons, trial: trial.active, scopes: apiKey.scopes });

from filmo_client import filmo

status, body, _ = filmo("GET", "/api/v1/account")
if status != 200:
    raise RuntimeError(f"getAccount {status} {(body or {}).get('code')}")

account = body["data"]
print(account["timezone"], account["currency"], account["addons"],
      account["trial"]["active"], account["apiKey"]["scopes"])

BASE="${FILMO_BASE_URL:-https://app.filmo.io}"
curl -sS -G "$BASE/api/v1/contacts" \
  -H "Authorization: Bearer $FILMO_API_KEY" \
  --data-urlencode "email=ana@example.com" \
  --data-urlencode "limit=500"

import { filmo } from "./filmo-client.mjs";

// Exact match on any address of the contact; the oldest active one wins, deterministically.
export async function findContact(email) {
  const res = await filmo("GET", "/api/v1/contacts", { query: { email, limit: 500 } });
  if (!res.ok) return { problem: res };
  const hits = res.body.data
    .filter((c) => c.emails.some((e) => e.email.toLowerCase() === email.toLowerCase()))
    .sort((a, b) => (a.status === "active" ? 0 : 1) - (b.status === "active" ? 0 : 1)
      || Date.parse(a.createdAt) - Date.parse(b.createdAt));
  return { contact: hits[0] ?? null };
}

from datetime import datetime

from filmo_client import filmo


# Exact match on any address of the contact; the oldest active one wins, deterministically.
def find_contact(email):
    status, body, _ = filmo("GET", "/api/v1/contacts", params={"email": email, "limit": 500})
    if status != 200:
        return {"problem": (status, body)}
    hits = [c for c in body["data"] if any(e["email"].lower() == email.lower() for e in c["emails"])]
    hits.sort(key=lambda c: (c["status"] != "active", datetime.fromisoformat(c["createdAt"].replace("Z", "+00:00"))))
    return {"contact": hits[0] if hits else None}

BASE="${FILMO_BASE_URL:-https://app.filmo.io}"
curl -sS -X POST "$BASE/api/v1/contacts" \
  -H "Authorization: Bearer $FILMO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: web-form-7c1e4a52-contact" \
  --data @- <<'JSON'
{
  "name": "Ana Example",
  "contactType": "person",
  "role": "lead",
  "email": "ana@example.com",
  "phone": "+34 600 000 000"
}
JSON

import { filmo } from "./filmo-client.mjs";

// submission.id: the id of THIS form submission, generated when the form was rendered.
export const createContact = (submission) =>
  filmo("POST", "/api/v1/contacts", {
    idempotencyKey: "web-form-" + submission.id + "-contact",
    body: {
      name: submission.name,
      contactType: "person",
      role: "lead",
      email: submission.email,
      phone: submission.phone,
    },
  });

from filmo_client import filmo


# submission["id"]: the id of THIS form submission, generated when the form was rendered.
def create_contact(submission):
    body = {
        "name": submission["name"],
        "contactType": "person",
        "role": "lead",
        "email": submission["email"],
        "phone": submission.get("phone"),
    }
    body = {k: v for k, v in body.items() if v}
    return filmo(
        "POST", "/api/v1/contacts", body=body,
        idempotency_key="web-form-" + submission["id"] + "-contact",
    )

BASE="${FILMO_BASE_URL:-https://app.filmo.io}"
curl -sS "$BASE/api/v1/crm/pipelines" \
  -H "Authorization: Bearer $FILMO_API_KEY"

import { filmo } from "./filmo-client.mjs";

let cached = null; // { at, pipelineId, stageId }

// Optional: with no pipeline or stage name set, send neither id (Filmo uses the default pipeline and
// its first stage) and never call listPipelines, so the key does not need crm:read.
export async function target({ refresh = false } = {}) {
  if (!process.env.FILMO_PIPELINE_NAME && !process.env.FILMO_STAGE_NAME) return {};
  if (cached && !refresh && Date.now() - cached.at < 3_600_000) return cached;
  const res = await filmo("GET", "/api/v1/crm/pipelines");
  if (!res.ok) throw new Error("listPipelines " + res.status + " " + res.body?.requestId);

  const pipelines = res.body.data;
  const pipeline =
    pipelines.find((p) => p.name === process.env.FILMO_PIPELINE_NAME) ??
    pipelines.find((p) => p.isDefault);
  const stage = pipeline?.stages.find((s) => s.name === process.env.FILMO_STAGE_NAME && s.type === "open");
  cached = { at: Date.now(), pipelineId: pipeline?.pipelineId, stageId: stage?.stageId };
  return cached;
}

import os
import time

from filmo_client import filmo

_cached = None  # {"at", "pipeline_id", "stage_id"}


# Optional: with no pipeline or stage name set, send neither id (Filmo uses the default pipeline and
# its first stage) and never call listPipelines, so the key does not need crm:read.
def target(refresh=False):
    global _cached
    if not os.environ.get("FILMO_PIPELINE_NAME") and not os.environ.get("FILMO_STAGE_NAME"):
        return {"pipeline_id": None, "stage_id": None}
    if _cached and not refresh and time.time() - _cached["at"] < 3600:
        return _cached
    status, body, _ = filmo("GET", "/api/v1/crm/pipelines")
    if status != 200:
        raise RuntimeError(f"listPipelines {status} {(body or {}).get('requestId')}")

    pipelines = body["data"]
    pipeline = next((p for p in pipelines if p["name"] == os.environ.get("FILMO_PIPELINE_NAME")), None)           or next((p for p in pipelines if p["isDefault"]), None)
    stage = next((s for s in (pipeline or {}).get("stages", [])
                  if s["name"] == os.environ.get("FILMO_STAGE_NAME") and s["type"] == "open"), None)
    _cached = {
        "at": time.time(),
        "pipeline_id": pipeline["pipelineId"] if pipeline else None,
        "stage_id": stage["stageId"] if stage else None,
    }
    return _cached

BASE="${FILMO_BASE_URL:-https://app.filmo.io}"
curl -sS -X POST "$BASE/api/v1/crm/opportunities" \
  -H "Authorization: Bearer $FILMO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: web-form-7c1e4a52-opportunity" \
  --data @- <<JSON
{
  "name": "Website enquiry from Ana Example",
  "description": "We need two cameras and a light kit for 2 to 4 November.",
  "contactId": "$CONTACT_ID",
  "source": "website_form",
  "sourceDetail": "/rent/cameras",
  "utmSource": "newsletter",
  "utmMedium": "email",
  "utmCampaign": "autumn-shoots"
}
JSON

import { filmo } from "./filmo-client.mjs";
import { target } from "./pipelines.mjs";

const clamp = (text, max) => (text == null ? undefined : String(text).slice(0, max));

// attempt 2 is the repeat with refreshed pipeline ids: another body needs another key.
export async function createOpportunity(submission, contactId, { attempt = 1 } = {}) {
  const { pipelineId, stageId } = await target();
  return filmo("POST", "/api/v1/crm/opportunities", {
    idempotencyKey: "web-form-" + submission.id + "-opportunity" + (attempt > 1 ? "-" + attempt : ""),
    body: {
      name: clamp("Website enquiry from " + submission.name, 200),
      description: submission.message,
      contactId,
      pipelineId,
      stageId,
      source: "website_form",
      sourceDetail: clamp(submission.page, 200),
      utmSource: clamp(submission.utm?.source, 200),
      utmMedium: clamp(submission.utm?.medium, 200),
      utmCampaign: clamp(submission.utm?.campaign, 200),
    },
  });
}

from filmo_client import filmo
from pipelines import target


def clamp(text, limit):
    return None if text is None else str(text)[:limit]


# attempt 2 is the repeat with refreshed pipeline ids: another body needs another key.
def create_opportunity(submission, contact_id, attempt=1):
    t = target()
    utm = submission.get("utm") or {}
    body = {
        "name": clamp("Website enquiry from " + submission["name"], 200),
        "description": submission.get("message"),
        "contactId": contact_id,
        "pipelineId": t["pipeline_id"],
        "stageId": t["stage_id"],
        "source": "website_form",
        "sourceDetail": clamp(submission.get("page"), 200),
        "utmSource": clamp(utm.get("source"), 200),
        "utmMedium": clamp(utm.get("medium"), 200),
        "utmCampaign": clamp(utm.get("campaign"), 200),
    }
    body = {k: v for k, v in body.items() if v is not None}
    return filmo(
        "POST", "/api/v1/crm/opportunities", body=body,
        idempotency_key="web-form-" + submission["id"] + "-opportunity" + (f"-{attempt}" if attempt > 1 else ""),
    )

import { createContact, findContact } from "./contact.mjs";
import { createOpportunity } from "./opportunity.mjs";
import { target } from "./pipelines.mjs";

// API path -> form field, per call. A path that is not here is a bug on your side, not the visitor's.
const CONTACT_FIELDS = { name: "name", email: "email", phone: "phone" };
const OPPORTUNITY_FIELDS = { description: "message" };

function visitorErrors(problem, fieldMap) {
  const fields = {};
  let ours = false;
  for (const e of problem.errors ?? []) {
    if (fieldMap[e.path]) fields[fieldMap[e.path]] = e.code; // show your own text for the code
    else ours = true; // includes the empty path (the whole body)
  }
  return { fields, ours };
}

// Never drop a lead: anything that is not the visitor's mistake goes to your outbox.
const queued = (submission, why) => {
  // outbox.save(submission, why) with your own storage, then retry with the SAME submission id
  return { status: 202, body: { received: true } };
};

export async function handleSubmission(submission) {
  try {
    return await processSubmission(submission);
  } catch (error) {
    // A network cut or a timeout throws before any answer arrives: the lead still goes to the outbox.
    return queued(submission, error);
  }
}

async function processSubmission(submission) {
  let found = await findContact(submission.email);
  if (found.problem) return queued(submission, found.problem);
  let contact = found.contact;

  if (!contact) {
    const res = await createContact(submission);
    if (res.status === 400) {
      const { fields, ours } = visitorErrors(res.body, CONTACT_FIELDS);
      return ours || !Object.keys(fields).length ? queued(submission, res.body) : { status: 400, body: { fields } };
    }
    if (!res.ok) return queued(submission, res.body);
    contact = res.body.data;
  }

  let res = await createOpportunity(submission, contact.id);
  if (res.status === 400) {
    // The 400 of a CRM write may carry no `path`, so it cannot tell you that a cached id went stale.
    // Read the pipelines again and repeat the write only if the ids you would send are different now.
    const before = await target();
    const after = await target({ refresh: true });
    if (after.pipelineId !== before.pipelineId || after.stageId !== before.stageId) {
      res = await createOpportunity(submission, contact.id, { attempt: 2 });
    }
  }
  if (res.status === 400) {
    const { fields, ours } = visitorErrors(res.body, OPPORTUNITY_FIELDS);
    return ours || !Object.keys(fields).length ? queued(submission, res.body) : { status: 400, body: { fields } };
  }
  if (!res.ok) return queued(submission, res.body);
  return { status: 201, body: { received: true } };
}

from contact import create_contact, find_contact
from opportunity import create_opportunity
from pipelines import target

# API path -> form field, per call. A path that is not here is a bug on your side, not the visitor's.
CONTACT_FIELDS = {"name": "name", "email": "email", "phone": "phone"}
OPPORTUNITY_FIELDS = {"description": "message"}


def visitor_errors(problem, field_map):
    fields, ours = {}, False
    for e in problem.get("errors") or []:
        if e["path"] in field_map:
            fields[field_map[e["path"]]] = e["code"]  # show your own text for the code
        else:
            ours = True  # includes the empty path (the whole body)
    return fields, ours


# Never drop a lead: anything that is not the visitor's mistake goes to your outbox.
def queued(submission, why):
    # outbox.save(submission, why) with your own storage, then retry with the SAME submission id
    return 202, {"received": True}


def handle_submission(submission):
    try:
        return _process_submission(submission)
    except Exception as error:  # a network cut or a timeout raises before any answer arrives
        return queued(submission, error)


def _process_submission(submission):
    found = find_contact(submission["email"])
    if "problem" in found:
        return queued(submission, found["problem"])
    contact = found["contact"]

    if contact is None:
        status, body, _ = create_contact(submission)
        if status == 400:
            fields, ours = visitor_errors(body, CONTACT_FIELDS)
            return queued(submission, body) if ours or not fields else (400, {"fields": fields})
        if status != 201:
            return queued(submission, body)
        contact = body["data"]

    status, body, _ = create_opportunity(submission, contact["id"])
    if status == 400:
        # The 400 of a CRM write may carry no path, so it cannot tell you that a cached id went stale.
        # Read the pipelines again and repeat the write only if the ids you would send are different now.
        before = target()
        after = target(refresh=True)
        if (after["pipeline_id"], after["stage_id"]) != (before["pipeline_id"], before["stage_id"]):
            status, body, _ = create_opportunity(submission, contact["id"], attempt=2)
    if status == 400:
        fields, ours = visitor_errors(body, OPPORTUNITY_FIELDS)
        return queued(submission, body) if ours or not fields else (400, {"fields": fields})
    if status != 201:
        return queued(submission, body)
    return 201, {"received": True}