BerthTime

Who this connection acts as (user or API key) and every company it may act for, with read or read + write access in each (a.k.a. whoami). Call it first when the user belongs to several companies or a call says access is denied; then pass `company` (id, @handle or exact name) to the other tools. No arguments. Returns: acting_as {type, name, email or prefix, app}, connection (api_key or oauth), all_companies, default_company and companies[] {id, name, handle, plan, plan_name, role, access, default}.

Takes no parameters.

List or search the company's own tracked shipments, newest first. Use it to find a shipment (free-text `q`: reference, customer reference, container number, vessel) or to filter by status (default active), carrier SCAC, phase, tag, ETA window (eta_after / eta_before, ISO 8601) or predicted eta_risk. For one shipment's full detail use get_shipment; for the next N days use list_arriving_shipments; for slipped ETAs use list_delayed_shipments; shipments other companies share with you are in list_shared_shipments. All arguments are optional. Returns: shipments[] {id, reference, ref_type, carrier, customer_reference, status, tracking_status, phase, pol, pod, eta, original_eta, delay_hours, predicted_eta, eta_risk, vessel, containers, booking_number, bl_number, tracked_via}, has_more, next_cursor. Paging: limit 1-100 (default 20); pass next_cursor as `cursor` for the next page.

Shipments that other companies (network connections) share with this company, read only, and open tracking requests (filter=requests). They are not the company's own shipments, so list_shipments, get_shipment and the write tools do not see them. All arguments are optional: filter (all or requests), free-text `q`. Returns: shipments[] {id, reference, ref_type, carrier, carrier_name, customer_reference, owner (@handle), owner_name, status, tracking_status, phase, eta, delay_hours, pol, pod, vessel, kind, request_status, paid_by_you, shared_at}, has_more, next_cursor. Paging: limit 1-100 (default 20) and `cursor`.

Everything about one shipment: summary, route (POL, transshipments, POD with actual and estimated times), current position estimate, carrier ETA and predicted ETA, and the latest actual events. Use it for "where is X" questions; for the full event history use get_shipment_events. `shipment` (required) is the BerthTime id, the tracked reference, or a container number on the shipment. Optional `events` (0-50, default 5) = how many latest actual events to include. Returns: shipment {id, reference, ref_type, carrier, customer_reference, status, tracking_status, phase, pol, pod, eta, original_eta, delay_hours, predicted_eta, eta_risk, vessel, containers, booking_number, bl_number, tracked_via, last_position, container_remarks}, route {stops[] {role, name, un_locode, arrival, departure}, legs[], current_position} or null, latest_events[]. Unknown reference: an error that suggests list_shipments or track_shipment.

The full DCSA-style event timeline of one shipment (gate in, load, departure, arrival, discharge, ...), oldest first. Use it when the user wants the history; get_shipment already includes the last few actual events. `shipment` (required) is the BerthTime id, the tracked reference, or a container number on the shipment. Optional: classifier (ACT actual, EST estimated, PLN planned; default all), limit (most recent N, 1-500, default 50). Returns: shipment_id, reference, events[] {at, timezone, precision, classifier, code, type, description, location, un_locode, vessel, voyage, container}. Times are UTC.

Active shipments not yet arrived whose carrier ETA falls within the next N days, soonest first. Use it for "what arrives this week"; for an exact date range or other filters use list_shipments with eta_after / eta_before. All arguments are optional: days (1-120, default 7), limit (1-200, default 50). Returns: days, shipments[] {id, reference, ref_type, carrier, customer_reference, status, tracking_status, phase, pol, pod, eta, original_eta, delay_hours, predicted_eta, eta_risk, vessel, containers, booking_number, bl_number, tracked_via}. No paging: raise limit or narrow days.

Active shipments whose carrier ETA has slipped versus the first ETA BerthTime saw, by at least min_delay_hours, most delayed first. Use it for "what is late"; for shipments predicted to be late from the vessel position use list_shipments with eta_risk=likely_late. All arguments are optional: min_delay_hours (0-10000, default 24), limit (1-200, default 50). Returns: min_delay_hours, shipments[] {id, reference, ref_type, carrier, customer_reference, status, tracking_status, phase, pol, pod, eta, original_eta, delay_hours, predicted_eta, eta_risk, vessel, containers, booking_number, bl_number, tracked_via} (delay_hours = the slip). No paging.

Check a number before tracking it: is it a container (ISO 6346 check digit), bill of lading or booking number, and which carrier issued it. Stores nothing and needs no company. Use it when the user is unsure what a number is; track_shipment detects on its own. Required: reference (3-64 characters, e.g. MSCU1234566). Returns: reference, ref_type, carrier_scac, carrier_name, confidence, check_digit_valid, note, suggested_carrier.

The carriers BerthTime knows: SCAC, name, which reference types each supports and whether tracking is live today. Use it to find the SCAC for track_shipment's `carrier` or to answer "do you support X". Optional: live_only (default false). Returns: carriers[] {scac, name, ref_types, tracking, ...}. No paging (the full list).

The company's plan and billable shipments for one month: included allowance, used, overage, cost so far and trial end. A shipment counts once per month when the carrier returned data for it. Use it for plan, quota or billing questions. Optional: month (YYYY-MM, UTC; default this month), include_shipments (default false) to list the counted shipments. Returns: month, plan, plan_name, included (null = unlimited), used, overage, projected_cost, currency, trial_ends_at, trial_active, and with include_shipments: shipments[] {shipment_id, reference, ref_type, first_counted_at, merged}.

The company's email alert rules (delay over N days, arrived, delivered, tracking failed), their scope (all shipments, a tag or a carrier) and how many people get them. Read only: rules are created and changed in the web app (Settings > Notifications). Optional: include_inactive (default false) to add paused rules. Returns: rules[] {id, name, summary, rule_type, delay_days, delay_mode, failure_count, scope, scope_value, is_active, recipients {all_members, members, extra_emails}}.

The company's support requests to the BerthTime team, most recent activity first. Use it to check the status of a request; to open one use create_support_request. Internal staff notes are never included. Optional: status (active = open + pending, the default; open, pending, resolved, closed or all), limit (1-100, default 20). Returns: tickets[] {id, number (BT-1234), subject, topic, status, priority, last_message_at, last_message_by, message_count, preview}, counts by status.

Start tracking a container, bill of lading or booking number. Type and carrier are detected when omitted; if the carrier is not recognised the shipment is added but not tracked, and you should call again with `carrier` (SCAC, see list_carriers). Already tracked references are returned as they are (archived ones are re-activated), so repeating a call is safe. Required: reference (4-64 characters, e.g. MSCU1234566). Optional: ref_type (container, bl, booking), carrier, customer_reference, tags, booking_number and bl_number (the other numbers of the same shipment, e.g. a container with its booking: one shipment, not three). Returns: result (created or exists), shipment {id, reference, ref_type, carrier, customer_reference, status, tracking_status, phase, pol, pod, eta, original_eta, delay_hours, predicted_eta, eta_risk, vessel, containers, booking_number, bl_number, tracked_via}. The first carrier data arrives in the background: check get_shipment a minute later. Counts towards the plan's monthly allowance once the carrier returns data. Needs write access: a read + write API key, or read + write access granted at sign-in by an owner or admin of the company.

Set, change or remove the booking and bill of lading numbers of a tracked shipment, or add container numbers to it. Use it when the user gives another number of a shipment already tracked (e.g. the booking of a container); track_shipment would start a new shipment instead. The tracker asks these numbers when the reference fails, and first when the carrier's booking query gives more than its container query (e.g. COSCO). `shipment` (required) is the BerthTime id, the tracked reference, or a container number on the shipment. Optional: booking_number, bl_number (an empty string removes it; omitted = unchanged), containers (ISO 6346, up to 20). At least one of them is required. Returns: shipment {id, reference, ref_type, carrier, customer_reference, status, tracking_status, phase, pol, pod, eta, original_eta, delay_hours, predicted_eta, eta_risk, vessel, containers, booking_number, bl_number, tracked_via}, retracking (true = a re-track was queued). A container number given as booking or B/L, or a malformed number, is an error. Needs write access: a read + write API key, or read + write access granted at sign-in by an owner or admin of the company.

The shipment's current public read-only tracking link (a URL anyone can open without logging in), if it has one. Use it before sending a link; use create_share_link when there is none. `shipment` (required) is the BerthTime id, the tracked reference, or a container number on the shipment. Returns: shipment_id, share_link {url, active, expires_at, view_count, ...} or null. Needs write access: a read + write API key, or read + write access granted at sign-in by an owner or admin of the company.

Create a public read-only tracking link for a shipment, or return the active one (safe to repeat). Anyone with the URL sees status, ETA, route and events, but no tags or company data. Disable or regenerate it in the web app. `shipment` (required) is the BerthTime id, the tracked reference, or a container number on the shipment. Returns: shipment_id, created (false = the existing link), share_link {url, active, expires_at, view_count, ...}. New links need a paid plan (the Free plan gets an error). Needs write access: a read + write API key, or read + write access granted at sign-in by an owner or admin of the company.

Open a support request with the BerthTime team on behalf of the user. Only when the user asks to contact support or report a problem; to see existing requests use list_support_requests. Required: subject (3-200 characters), message (plain text). Optional: topic (support, sales, billing, partnership, other; default support), priority (normal or high, high only when the user says it is urgent). Returns: id, number (BT-1234), status, requester_email. The team answers by email and in the web app. Each call opens a new request, so do not repeat it. Needs write access: a read + write API key, or read + write access granted at sign-in by an owner or admin of the company.

Stop tracking a shipment. Its history is kept and track_shipment with the same reference re-activates it. Only when the user asks to stop or remove a shipment. `shipment` (required) is the BerthTime id, the tracked reference, or a container number on the shipment. Returns: shipment_id, status (archived). Archiving an archived shipment changes nothing. Needs write access: a read + write API key, or read + write access granted at sign-in by an owner or admin of the company.