Net::D...:Phone(3pm)

📦
version 1.02 · 2 versions
  • 1.02 · debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
  • 1.02 · ubuntu jammy
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

✨ NAME ✨

ok so this is Net::Duo::Admin::Phone — a whole Perl object that's basically the ✨representation✨ of a Duo phone. yes bestie, like an actual phone object, it's giving very much main character energy 💅

🌸 SYNOPSIS 🌸

my $decoded_json = get_json();
my $phone = Net::Duo::Admin::Phone->new($decoded_json);
say $phone->number;

like... that's it. that's the whole vibe. you hand it json, you get a phone. iconic 🎀

💖 REQUIREMENTS 💖

okay so you're gonna need Perl 5.14 or later (no ancient perls, we don't do that here 💀) plus these modules, all of which live on CPAN:

  • HTTP::Request and HTTP::Response (both part of HTTP::Message)
  • JSON
  • LWP (aka libwww-perl, iykyk)
  • Perl6::Slurp
  • Sub::Install
  • URI::Escape (part of URI)

🦋 DESCRIPTION 🦋

A Net::Duo::Admin::Phone object is a Perl representation of a Duo phone, exactly as the Duo Admin API hands it back. usually you get one via the phones() method, or lowkey nested inside a user that came from the users() method 👀. it's carrying around a whole bunch of info about a phone. periodt.

👑 CLASS METHODS 👑

create(DUO, DATA)

bestie this one creates a brand new phone in Duo and hands you back the resulting phone as a shiny new Net::Duo::Admin::Phone object ✨

  • DUO — the Net::Duo object that should be used to perform the creation.
  • DATA — a reference to a hash, and its keys go like this:
    • extension — the extension. Optional.
    • name — the name of the phone. Optional.
    • number — the phone number. Optional.
    • platform — the platform of phone for Duo Mobile, or "unknown" for a generic phone type. for the list of valid values, go look at the Duo Admin API documentation 📖. Optional.
    • postdelay — the time (in seconds) to wait after the extension is dialed and before the speaking the prompt. Optional.
    • predelay — the time (in seconds) to wait after the number picks up and before dialing the extension. Optional.
    • type — the type of the phone. peep the type() method down below for the possible values 👇. Optional.

new(DUO, DATA)

makes a fresh Net::Duo::Admin::Phone object out of a full data set.

  • DUO — the Net::Duo object used for any further actions on this object.
  • DATA — the data structure the Duo REST API returned for a single user, after JSON decoding.

new(DUO, ID)

this one makes a Net::Duo::Admin::Phone by ID 🎀

  • DUO — the Net::Duo object used to retrieve the phone from Duo, and used for any subsequent operations too.
  • ID — should be the Duo identifier of the phone.
ngl this constructor is told apart from the previous one by checking whether ID is a reference. that's the whole trick 🤫

🔥 INSTANCE ACTION METHODS 🔥

activation_url([ARGS])

requests activation URLs (and optionally an install URL too, fancy 💅) for this phone. ARGS is an optional reference to a hash, and its keys should be chosen from:

  • install — if set to a true value, request an installation URL for this phone as well as the activation URLs. this is a URL that, when opened, prompts the user to install Duo Mobile. the default is to not request an installation URL.
  • valid_secs — how many seconds these activation URLs should stay valid for. default is 86,400 (that's one whole day, bestie).

and the return value? a reference to a hash containing these keys:

  • activation_url — opening this URL with the Duo Mobile app will complete activation ✅
  • activation_barcode — URL of an image you can scan with Duo Mobile to complete activation. activating with this image or with the activation URL produces the exact same result, no cap.
  • installation_url — opening this URL on the phone prompts the user to install Duo Mobile. this will only be present if the install argument is set to a true value.
  • valid_secs — the number of seconds the activation code is valid for. normally this is the same as the valid_secs argument in the request if it was present — unless Duo rejected the requested validity interval 🙈

commit()

commits all the changes you made via the set_*() methods to Duo. and listen: until you call this, anything you did with set_*() is only internal to the object and not reflected in Duo. it's giving "draft mode" 😭

after commit(), the object's internal representation gets refreshed to match the new data the Duo API returns for that object. so lowkey, other fields of the object may change after commit() if some other user changed other, unrelated fields in the object. yeah. it happens.

best way to think about this method? it's a synchronize operation: changed data gets written back, overwriting what's in Duo, and unchanged data may get overwritten by whatever's currently in Duo, if it's different. that's the deal 🫶

delete()

deletes this phone from Duo. after this call completes successfully, the Net::Duo::Admin::Phone object should be considered read-only, since no further changes to the object can be meaningfully sent to Duo. it's done, it's retired, it's graduated 🎓

json()

converts the data stored in the object into JSON and returns the results. the resulting JSON should match the JSON you'd get back from the Duo web service when retrieving the same object (plus any changes you made locally via the set_*() methods). this is mainly for debugging dumps, or for passing Duo objects along to other systems via further JSON APIs 📦

send_sms_passcodes()

generates a whole new batch of SMS passcodes and sends them to the phone in a single SMS message 📱. how many passcodes get sent is a global setting on the Duo account — so that's on your Duo admin, not on you.

💜 INSTANCE DATA METHODS 💜

so some of these fields have set_*() methods. those methods replace the value of the field in its entirety with the new value you pass in. and important: this change is only made locally in the object until commit() gets called. don't forget, bestie 😤

activated()

whether the phone has been activated for Duo Mobile.

capabilities()

a list of phone capabilities, chosen from these values:

  • "push" — the device is activated for Duo Push.
  • "phone" — the device can receive phone calls.
  • "sms" — the device can receive batches of SMS passcodes.

extension() / set_extension(EXTENSION)

the extension for this phone, if any.

name() / set_name(NAME)

the name of this phone.

number() / set_number(NUMBER)

the number for this phone, without any extension.

phone_id()

the unique ID of this phone, as generated by Duo on phone creation. that's the ✨birth certificate✨

platform() / set_platform(PLATFORM)

the platform of phone for Duo Mobile, or "unknown" for a generic phone type. for the list of valid values, see the Duo Admin API documentation 📖

postdelay() / set_postdelay(POSTDELAY)

the time (in seconds) to wait after the extension is dialed and before the speaking the prompt.

predelay() / set_predelay(PREDELAY)

the time (in seconds) to wait after the number picks up and before dialing the extension.

sms_passcodes_sent()

whether SMS passcodes have been sent to this phone.

type() / set_type(TYPE)

the type of phone, chosen from "unknown", "mobile", or "landline".

users()

the users associated with this phone, as a list of Net::Duo::Admin::User objects 🫂

🎀 AUTHOR 🎀

Russ Allbery <rra@cpan.org>

Copyright 2014 The Board of Trustees of the Leland Stanford Junior University

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

like yeah the caps are dramatic but that's just how legal text is, no shade 💀

🌈 SEE ALSO 🌈

okay that's the whole page bestie, you're officially a Duo phone expert 💅✨ this was Net::D...:Phone(3pm), a user-contributed Perl doc, generated with perl v5.36.0 on 2022-12-18 — go forth and slay 🦋👑

📦 where this page comes from