Sameday

8.12

Sameday🔗ℹ

Bogdan Popa <bogdan@defn.io>

(require sameday)

package: sameday

This package provides a Racket client for the Sameday API.

1 Usage🔗ℹ

Instantiate and install a client:

(require sameday)

(define c
(make-client #:username "a-username"
#:password "a-password"))

(current-client c)

Then start making API calls:

(get-services)

Alternatively, all API calls can be provided an explicit client:

(get-services c)

2 Accessors🔗ℹ

Most calls return jsexpr? values and special, racket-y, accessors are provided for each data type. Every data type also provides a smart constructor that takes in optional keyword arguments for every field.

> (recipient #:type 'individual)
'#hasheq((address . #f)
         (city . #f)
         (county . #f)
         (email . #f)
         (name . #f)
         (personType . 0)
         (phoneNumber . #f)
         (postalCode . #f))
>
> (define a-recipient
   (recipient
    #:city-id 1
    #:county-id 2
    #:address "111 Example St."
    #:name "John Doe"
    #:phone "1234567890"
    #:email "john.doe@example.com"
    #:type 'individual))
> a-recipient
'#hasheq((address . "111 Example St.")
         (city . 1)
         (county . 2)
         (email . "john.doe@example.com")
         (name . "John Doe")
         (personType . 0)
         (phoneNumber . "1234567890")
         (postalCode . #f))
>
> (recipient-name a-recipient)
"John Doe"

3 Reference🔗ℹ

3.1 Client🔗ℹ

procedure
(make-client #:username username
#:password password) → client?
username : string?
password : string?

Returns a new Sameday API client whose requests will be authenticated using the given username and password.

procedure
(client? v) → boolean?
v : any/c

Returns #t when v is a Sameday API client.

parameter
(current-client) → client?
(current-client client) → void?
client : client?
= #f

A parameter that holds the current Sameday API client.

parameter
(current-client-root) → string?
(current-client-root root) → void?
root : string?
= "https://api.sameday.ro"

A parameter that holds the current API root. All request URLs are relative to this address.

3.2 AWB🔗ℹ

value
cents/c : (and/c exact-integer? (>=/c 100))

procedure
(recipient? v) → boolean?
  v : any/c
procedure
(recipient #:city-id city-id
#:county-id county-id
#:address address
#:postal-code postal-code
#:name name
#:phone phone
#:email email
#:type type) → recipient?
  city-id : exact-positive-integer?
  county-id : exact-positive-integer?
  address : string?
  postal-code : string?
  name : string?
  phone : string?
  email : string?
  type : (or/c 'individual 'company)
procedure
(recipient-city-id r) → exact-positive-integer?
  r : recipient?
procedure
(recipient-county-id r) → exact-positive-integer?
  r : recipient?
procedure
(recipient-address r) → string?
  r : recipient?
procedure
(recipient-postal-code r) → string?
  r : recipient?
procedure
(recipient-name r) → string?
  r : recipient?
procedure
(recipient-phone r) → string?
  r : recipient?
procedure
(recipient-email r) → string?
  r : recipient?
procedure
(recipient-type r) → (or/c 'individual 'company)
  r : recipient?

procedure
(awb? v) → boolean?
  v : any/c
procedure
(awb-number a) → exact-positive-integer?
  a : awb?
procedure
(awb-cost a) → cents/c
  a : awb?
procedure
(awb-parcels a) → (listof parcel?)
  a : awb?

procedure
(awb-estimate? v) → boolean?
  v : any/c
procedure
(awb-estimate-amount a) → cents/c
  a : awb-estimate?
procedure
(awb-estimate-currency a) → string?
  a : awb-estimate?

procedure
(awb-status? v) → boolean?
v : any/c
procedure
(awb-status-parcels a) → (listof parcel?)
a : awb-status?

procedure
(parcel? v) → boolean?
  v : any/c
procedure
(parcel-status-id p) → exact-positive-integer?
  p : parcel?
procedure
(parcel-status p) → string?
  p : parcel?
procedure
(parcel-status-label p) → string?
  p : parcel?
procedure
(parcel-status-state p) → string?
  p : parcel?
procedure
(parcel-status-date p) → moment?
  p : parcel?
procedure
(parcel-county p) → string?
  p : parcel?
procedure
(parcel-reason p) → string?
  p : parcel?
procedure
(parcel-transit-location p) → string?
  p : parcel?
procedure
(parcel-awb p) → string?
  p : parcel?
procedure
(parcel-details p) → string?
  p : parcel?
procedure
(parcel-returning? p) → boolean?
  p : parcel?

procedure
(parcel-dimensions? v) → boolean?
  v : any/c
procedure
(parcel-dimensions-weight p) → real?
  p : parcel-dimensions?
procedure
(parcel-dimensions-width p) → real?
  p : parcel-dimensions?
procedure
(parcel-dimensions-height p) → real?
  p : parcel-dimensions?
procedure
(parcel-dimensions-length p) → real?
  p : parcel-dimensions?

procedure
(create-awb! recipient
#:service-id service-id
#:pickup-point-id pickup-point-id
#:contact-person-id contact-person-id
[ #:package-type package-type
#:parcel-dimensions parcel-dimensions
#:insured-value insured-value
#:cod-amount cod-amount
#:reference reference
#:estimate? estimate?
#:client client])
→ (or/c awb? awb-estimate?)
  recipient : recipient?
  service-id : exact-positive-integer?
  pickup-point-id : exact-positive-integer?
  contact-person-id : exact-positive-integer?
  package-type : 'parcel = (or/c 'parcel 'envelope 'large)
  parcel-dimensions : null = (listof parcel-dimensions?)
  insured-value : 0 = cents/c
  cod-amount : 0 = cents/c
  reference : #f = (or/c #f string?)
  estimate? : #f = boolean?
  client : (current-client) = client?

Creates an AWB.

When #:estimate? is #t, an awb-estimate? is returned instead and no AWB is created.

The #:reference keyword argument can be used to provide an internal reference.

procedure
(delete-awb! awb [c]) → void?
awb : string?
c : (current-client) = client?

Deletes the awb whose id is awb.

procedure
(call-with-awb-pdf awb
f
[ #:type type
#:client client]) → any
  awb : string?
  f : (-> input-port? any)
  type : 'A6 = (or/c 'A4 'A6)
  client : (current-client) = client?

Calls f with an input port containing the PDF data of the AWB whose id is awb.

procedure
(get-awb-status awb [c]) → awb-status?
awb : string?
c : (current-client) = client?

Gets the status and history of the AWB whose id is awb.

3.3 Geolocation🔗ℹ

procedure
(county? v) → boolean?
  v : any/c
procedure
(county-id c) → exact-positive-integer?
  c : county?
procedure
(county-name c) → string?
  c : county?
procedure
(county-code c) → string?
  c : county?

procedure
(city? v) → boolean?
  v : any/c
procedure
(city-id c) → exact-positive-integer?
  c : city?
procedure
(city-name c) → string?
  c : city?
procedure
(city-county c) → county?
  c : city?
procedure
(city-village c) → string?
  c : city?
procedure
(city-postal-code c) → string?
  c : city?
procedure
(city-logistic-circle c) → string?
  c : city?
procedure
(city-delivery-agency c) → string?
  c : city?
procedure
(city-pickup-agency c) → string?
  c : city?
procedure
(city-extra-km c) → real?
  c : city?

procedure
(get-counties [ name
#:page page
#:per-page per-page
#:client client]) → (page/c (listof county?))
  name : #f = (or/c #f string?)
  page : 1 = exact-positive-integer?
  per-page : 100 = exact-positive-integer?
  client : (current-client) = client?

Returns a list of known counties, optionally filtered by name.

procedure
(get-cities [ name
#:county-id county-id
#:postal-code postal-code
#:page page
#:per-page per-page
#:client client])
→ (page/c (listof city?))
  name : #f = (or/c #f string?)
  county-id : #f = (or/c #f exact-positive-integer?)
  postal-code : #f = (or/c #f string?)
  page : 1 = exact-positive-integer?
  per-page : 100 = exact-positive-integer?
  client : (current-client) = client?

Returns a list of known cities, optionally filtered by name, county and postal code.

3.4 Pickup Points🔗ℹ

procedure
(contact? v) → boolean?
  v : any/c
procedure
(contact-id p) → exact-positive-integer?
  p : contact?
procedure
(contact-name p) → string?
  p : contact?
procedure
(contact-phone-number p) → string?
  p : contact?
procedure
(contact-default? p) → boolean?
  p : contact?

procedure
(pickup-point? v) → boolean?
  v : any/c
procedure
(pickup-point-id p) → exact-positive-integer?
  p : pickup-point?
procedure
(pickup-point-county-id p) → exact-positive-integer?
  p : pickup-point?
procedure
(pickup-point-city-id p) → exact-positive-integer?
  p : pickup-point?
procedure
(pickup-point-address p) → string?
  p : pickup-point?
procedure
(pickup-point-default? p) → boolean?
  p : pickup-point?
procedure
(pickup-point-contacts p) → (listof contact?)
  p : pickup-point?
procedure
(pickup-point-alias p) → string?
  p : pickup-point?

procedure
(get-pickup-points [c]) → (page/c (listof pickup-point?))
c : client? = (current-client)

Get the list of pickup points registered with your account.

3.5 Services🔗ℹ

procedure
(delivery-type? v) → boolean?
  v : any/c
procedure
(delivery-type-id t) → exact-integer?
  t : delivery-type?
procedure
(delivery-type-name t) → string?
  t : delivery-type?

procedure
(service? v) → boolean?
  v : any/c
procedure
(service-id s) → exact-integer?
  s : service?
procedure
(service-name s) → string?
  s : service?
procedure
(service-type s) → delivery-type?
  s : service?
procedure
(service-code s) → string?
  s : service?
procedure
(service-default? s) → boolean?
  s : service?

procedure
(get-services [c]) → (page/c (listof service?))
c : client? = (current-client)

Get the list of services provided by Sameday.

3.6 Pagination🔗ℹ

procedure
(page? v) → boolean?
  v : any/c
procedure
(page-data p) → list?
  p : page?
procedure
(page-pages p) → exact-positive-integer?
  p : page?
procedure
(page-current p) → exact-positive-integer?
  p : page?
procedure
(page-per-page p) → exact-positive-integer?
  p : page?
procedure
(page-total p) → exact-nonnegative-integer?
  p : page?

procedure
(page/c p) → (-> any/c boolean?)
p : (-> any/c boolean?)

A higher-order contract that applies p to a page’s data.