SMS Href

SMS Href creates SMS URL strings, updates existing SMS URL strings, or updates all href attributes containing SMS URLs on a web page or in a defined DOM context.

You can avoid this library and use the universal separator
;?& (all three characters in that order),
but it doesn't work everywhere.

Installation
Usage
API
- Instance
  - Custom separator
- fixAll
- fixValue
- create
Types

Installation

Manager	Command
	`npm install sms-href`
	`yarn add sms-href`
	`pnpm add sms-href`

DEV runners

runner	output	description
`npm run build`	`./lib/*/`	Transpile from Typescript to Javascript
`npm run build:pack`	`./sms-href-{package-json-version}.tgz`	Create NPM package file (`*.tgz`)
`npm run demo`	`./demo/dist/demo.js`	Build demo and measure minimal build size

Basic usage (without catching outputs)

import {SmsHref} from "sms-href";

const smsHref: SmsHref = new SmsHref();

// As promise
smsHref.fixAll().catch();

// OR sync
try {
    await smsHref.fixAll();
} catch (e) {
}

Tested platforms

Android	iOS	iPadOS
10 (Quince Tart)	6	6
12 (Snow Cone)	8	8
13 (Tiramisu)	12	12
	15	15
	16	16
	17 (beta)	17 (beta)

API

Instance

Syntax:

`new SmsHref( [ options: Options ] )`

Instance of SmsHref

Example:

const smsHref: SmsHref = new SmsHref();

Constructor parameters:

	type	default	description
[`options`]	`Options`		Configuration of custom separator and allowed devices - Show detail
[`options.allow`]	`Devices`		List of enable/disable devices - Show detail
[`options.allow.mobile` = true ]	`boolean`	`true`	Enable/disable href update for mobile devices
[`options.allow.tablet` = true ]	`boolean`	`true`	Enable/disable href update for tablet devices
[`options.allow.facebook` = true ]	`boolean`	`true`	Enable/disable href update for Facebook app web view
[`options.separator` = null ]	`string` `null`	`null`	User defined SMS body (`body=`) separator. Read more NOTE: Internal platform detection and allowed devices list will be disabled.
[`options.encode` = true ]	`boolean`	`true`	Enable/disable message text encoding globally ( e.g., `encodeURIComponent` ) NOTE: Methods fixValue() and create() have their own parameter for enable/disable encoding and this global parameter can be overridden.

Example (disable tablets and facebook app web view):

const smsHref: SmsHref = new SmsHref({
    allow: {
        facebook: false,
        tablet: false
    }
});

Custom separator definition

If you want to define your own separator, you can use existed separator constants

constant name	value	type	description
`ANDROID_SEPARATOR`	`?`	`string`	Body separator `?body=` for `Android` platform
`IOS_7_AND_LOWER_SEPARATOR`	`;`	`string`	Body separator `;body=` for `IOS <= 7` platform
`IOS_8_AND_HIGHER_SEPARATOR`	`&`	`string`	Body separator `&body=` for `IOS >= 8` platform
`MIN_IOS_VERSION`	`7`	`number`	Value is `7` - because `iOS7` allegedly doesn't support `sms:` href links.

NOTE: IOS 7 allegedly does not support sms: protocol.

Example:

import {
    SmsHref,
    MIN_IOS_VERSION,
    ANDROID_SEPARATOR,
    IOS_7_AND_LOWER_SEPARATOR,
    IOS_8_AND_HIGHER_SEPARATOR
} from "sms-href";

// Custom
function customSeparatorMechanism(): string | null {
    const platform: CustomPlatformDetection = new CustomPlatformDetection();

    if (platform.name === 'Android')
        return ANDROID_SEPARATOR;

    if (platform.name === 'IOS') {
        if (platform.version.major <= MIN_IOS_VERSION)
            return IOS_7_AND_LOWER_SEPARATOR
        return IOS_8_AND_HIGHER_SEPARATOR;
    }

    return null;
}

// Instance
const smsHref: SmsHref = new SmsHref({
    separator: customSeparatorMechanism()
});

fixAll

Syntax:

`async fixAll( [ context: Element | HTMLElement | Document ] ) : Promise<ResultCode>`

Finds and update all anchor links with sms: protocol value by current platform in set DOM context.

	type	default	description
[`context` = document ]	`Element` `HTMLElement` `Document`	`document`	Defines parent DOM node for search
returns	`Promise<ResultCode>`
throws	`Promise.catch<ResultCode>`

Example:

await smsHref.fixAll();

Example with custom defined context:

const context: HTMLElement = document.querySelector('.context-element');

await smsHref.fixAll(context);

Example with using resultCode in Promise<ResultCode>.

import {
    SmsHref,
    ResultCode,
    CODE_SUCCESS,
    CODE_NOT_FOUND,
    CODE_UNSUPPORTED_OS
} from "sms-href";

const smsHref: SmsHref = new SmsHref();

smsHref.fixAll()
    .then((resultCode: ResultCode): void => {
        if (resultCode === CODE_SUCCESS)
            console.log(`All sms: href values in anchors was updated`);
    })
    .catch((resultCode: any): void => {
        if (resultCode === CODE_NOT_FOUND)
            console.log(`'Anchors with sms: href value doesn't exist'`);
        else if (resultCode === CODE_UNSUPPORTED_OS)
            console.log(`Current platform doesn't support sms: href protocol`);
    });

ResultCode constants list:

constant name	value	type	status	description
`CODE_SUCCESS`	`200`	`number`	Ok	All sms: href values in anchors was updated
`CODE_NOT_FOUND`	`404`	`number`	Not found	Anchors with sms: href value doesn't exist
`CODE_UNSUPPORTED_OS`	`501`	`number`	Not Implemented	Current platform doesn't support sms: href protocol

fixValue

Syntax:

`async fixValue( smsValue: string [, encode: boolean ] ) : Promise<string>`

Update input string value by current platform.

	type	default	description
`smsValue`	`string`		Input string for update
[`encode`]	`boolean`	Constructor `options.encode` value	Enable/disable message text encoding ( e.g., `encodeURIComponent` )
returns	`Promise<string>`		Valid SMS Href `sms:`anchor string

Example:

await smsHref.fixValue('1234@body=Your message');
// Android  --> sms:1234?body=Your%20message
// IOS <= 7 --> sms:1234;body=Your%20message
// IOS >= 8 --> sms:1234&body=Your%20message

Example (with disabled message encoding):

await smsHref.fixValue('1234@body=Your message', false);
// Android  --> sms:1234?body=Your message
// IOS <= 7 --> sms:1234;body=Your message
// IOS >= 8 --> sms:1234&body=Your message

create

Syntax:

`async create( smsConfiguration: SmsConfiguration [, encode: boolean] ) : Promise<string>`

Creates sms: href string from phone number and sms message text.

	type	default	description
`smsConfiguration`	`SmsConfiguration`
`smsConfiguration[.phone]`	`string` `number`		SMS Phone number
`smsConfiguration[.message]`	`string`		SMS message text
[ `encode` ]	`boolean`	Constructor `options.encode` value	Enable/disable message text encoding ( e.g., `encodeURIComponent` )
returns	`Promise<string>` - Valid SMS Href `sms:`anchor string
throws	`Promise.reject<TypeError>`		If `phone` and `message` are both not provided

NOTES:

Phone and message are both optional, but one of them must be provided.
Phone number format validation is not implemented. You should use own validation.
SMS message format validation is not implemented. You should use own validation.

Example:

await smsHref.create({
    phone: 1234,
    message: 'Your message'
});
// Android  --> sms:1234?body=Your%20message
// IOS <= 7 --> sms:1234;body=Your%20message
// IOS >= 8 --> sms:1234&body=Your%20message

Example (with disabled message encoding):

await smsHref.create({
    phone: 1234,
    message: 'Your message'
}, false);
// Android  --> sms:1234?body=Your message
// IOS <= 7 --> sms:1234;body=Your message
// IOS >= 8 --> sms:1234&body=Your message

Types

ResultCode

type ResultCode = number;

Options

type Options = {
    allow?: Devices;
    separator?: string | null;
    encode?: boolean;
}

Devices

type Devices = {
    mobile?: boolean;
    tablet?: boolean;
    facebook?: boolean;
};

SmsConfiguration

type SmsConfiguration = {
    phone?: string | number;
    message?: string;
}

License

References

sms-href

SMS Href

Installation

DEV runners

Basic usage (without catching outputs)

Tested platforms

API

Instance

`new SmsHref( [ options: Options ] )`

Custom separator definition

fixAll

`async fixAll( [ context: Element | HTMLElement | Document ] ) : Promise<ResultCode>`

fixValue

`async fixValue( smsValue: string [, encode: boolean ] ) : Promise<string>`

create

`async create( smsConfiguration: SmsConfiguration [, encode: boolean] ) : Promise<string>`

Types

ResultCode

Options

Devices

SmsConfiguration

License

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

Weekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

sms-href

SMS Href

Installation

DEV runners

Basic usage (without catching outputs)

Tested platforms

API

Instance

new SmsHref( [ options: Options ] )

Custom separator definition

fixAll

async fixAll( [ context: Element | HTMLElement | Document ] ) : Promise<ResultCode>

fixValue

async fixValue( smsValue: string [, encode: boolean ] ) : Promise<string>

create

async create( smsConfiguration: SmsConfiguration [, encode: boolean] ) : Promise<string>

Types

ResultCode

Options

Devices

SmsConfiguration

License

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

`new SmsHref( [ options: Options ] )`

`async fixAll( [ context: Element | HTMLElement | Document ] ) : Promise<ResultCode>`

`async fixValue( smsValue: string [, encode: boolean ] ) : Promise<string>`

`async create( smsConfiguration: SmsConfiguration [, encode: boolean] ) : Promise<string>`

Weekly Downloads